Home Explore Help
Sign In
FFDN
/
isp-format
3
0
Fork 1
Files Issues 0 Pull Requests 0 Wiki
Tree: d9363bd4e2
Branches Tags
isp-format
/
ispformat
/
specs
/
0.1
/
isp-schema-spec.rst

isp-schema-spec.rst 4.0 KB
History Raw

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788 
  1. ==========
    2. 

  2. ISP format
    3. 

  3. ==========
    4. 

  4. ------------------------------------------------
    5. 

  5. Schema specification & implementation guidelines
    6. 

  6. ------------------------------------------------
    7. 

  7. 

  8. :Editor:
    9. 

  9.     Gu1 <gu1@cafai.fr>
    10. 

  10. :Authors:
    11. 

  11.     FFDN diyisp schema working group
    12. 

  12. :Revision:
    13. 

  13.     draft-1 (0.1)
    14. 

  14. :Date:
    15. 

  15.     October 2013
    16. 

  16. 

  17. 

  18. **Abstract:**
    19. 

  19.  The ISP format is a file format created and supported by the FDN Federation (FFDN) in order to help ISPs sharing its value to document and publish relevent informations regarding their status and progress in a common format.
    20. 

  20. 

  21. 

  22. .. contents:: **Table of Contents**
    23. 

  23. 

  24. 

  25. 

  26. 1. Introduction
    27. 

  27. ===============
    28. 

  28. 

  29. The ISP format is meant to allow an ISP to share relevant data and informations, such as its number of subscribers, the URL of its websites, chatrooms, etc... It was mostly created with small/diy/non-profit ISPs in mind, such as those in the FFDN.
    30. 

  30. 

  31. 1.1. Definitions
    32. 

  32. ----------------
    33. 

  33. * The ISP format itself is based on the JSON data format. The JavaScript Object Notation (JSON) format and its basic types are defined in [RFC4627]_.
    34. 

  34. * The ISP format is mostly specified as a JSON Schema file, a JSON-based format for defining the structure of JSON data. JSON Schema is defined in the following IETF draft [json-schema-04]_.
    35. 

  35. * The ISP format relies on HTTP/1.1 for data transfer [RFC2616]_.
    36. 

  36. * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]_.
    37. 

  37. 

  38. 

  39. 2. JSON Schema definition of the format
    40. 

  40. =======================================
    41. 

  41. .. include:: ../schema/0.1/isp.json
    42. 

  42.     :literal:
    43. 

  43. 

  44. 

  45. 3. Implementating the format
    46. 

  46. ============================
    47. 

  47. 

  48. An ISP implementing the ISP format MUST serve the file as a valid HTTP ressource named isp.json placed at the root (/) of its HTTP server.
    49. 

  49. 

  50. The ressource SHOULD be served on the ISP's main website (e.g. http://www.isp.org/isp.json). If that is not possible for some reason, the ISP MUST serve it on a subdomain (e.g. http://api.isp.org/isp.json).
    51. 

  51. 

  52. The ressource SHOULD be served with a MIME type of "application/json".
    53. 

  53. 

  54. The ressource SHOULD be reachable over HTTPS ([RFC2818]_).
    55. 

  55. 

  56. The ressource MUST be served over HTTP version 1.1.
    57. 

  57. 

  58. 

  59. 3.1 Caching considerations
    60. 

  60. --------------------------
    61. 

  61. 

  62. The HTTP ressource SHOULD provide an expiration time, either through the Cache-Control header's max-age directive or the Expires header.
    63. 

  63. 

  64. Please note that clients may choose to ignore the provided expiration time in cases where the value is deemed to low (e.g. a few seconds) or too high (e.g. a month).
    65. 

  65. 

  66. Moreover, not all Cache-Control directives are guaranteed to be respected by clients, such as private, must-revalidate, no-cache, no-store.
    67. 

  67. 

  68. A client may choose to cache the response for a low amount of time even in cases where a ressource explicitely disabled caching by providing a max-age of 0 or an Expires date set in the past.
    69. 

  69. 

  70. Additionally, a ressource SHOULD implement conditional requests by providing an ETag or Last-Modified header and responding to the If-Modified-Since or If-None-Match request headers properly.
    71. 

  71. 

  72. 

  73. 3. References
    74. 

  74. =============
    75. 

  75. 

  76. .. [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)",
    77. 

  77.              `RFC 4627 <http://tools.ietf.org/html/rfc4627>`_, July 2006.
    78. 

  78. .. [json-schema-04] "JSON Schema: core definitions and terminology",
    79. 

  79.                     `draft-zyp-json-schema-04 <http://tools.ietf.org/html/draft-zyp-json-schema-04>`_, January 31, 2013.
    80. 

  80. .. [RFC2616] Fielding, R., Gettys, J. Mogul, J., Frystyk, H., Masinter, L., Leach P., and T. Berners-Lee,
    81. 

  81.              "Hypertext Transfer Protocol -- HTTP/1.1", `RFC 2616 <http://tools.ietf.org/html/rfc2616>`_, June 1999.
    82. 

  82. .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", `RFC 2119 <http://tools.ietf.org/html/rfc2119>`_, March 1997.
    83. 

  83. .. [RFC2818] Rescorla, E., "HTTP Over TLS", `RFC 2818 <https://tools.ietf.org/html/rfc2818>`_, May 2000.
    84. 

  84. 

  85. 

  86. Appendix A. ISPs Examples
    87. 

  87. =========================
    88. 

  88. TODO
    89.