Move to SF for data model

For #1.

Author: mnot

draft-ietf-httpapi-link-hint.md

@@ -34,6 +34,7 @@ normative:
   WEB-LINKING: RFC8288
   JSON: RFC8259
   URI: RFC3986
+  STRUCTURED-FIELDS: RFC9651
 
 
 --- abstract
@@ -55,7 +56,7 @@ Hints are just that -- they are not a contract, and are to only be taken as advi
 
 More fine-grained information might also be gathered by interacting with the resource (e.g., via a GET), or by another resource containing it (such as a widgets collection) or describing it (e.g., one linked to it with a "describedby" link relation).
 
-There is not a single way to convey hints with a link; rather, it is expected that this will be done by individual link serialisations (see {{Section 3.4.1 of WEB-LINKING}}). However, {{link_header}} does recommend how to include link hints in the existing Link header field.
+There is not a single way to convey hints with a link; rather, it is expected that this will be done by individual link serialisations (see {{Section 3.4.1 of WEB-LINKING}}).
 
 
 ## Notational Conventions
@@ -65,30 +66,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 # HTTP Link Hints {#link_hints}
 
-A HTTP link hint is a (key, value) tuple that describes the target resource of a Web link {{WEB-LINKING}}, or the link itself. The value's canonical form is a JSON {{JSON}} data structure specific to that hint.
+A HTTP link hint is a (key, value) tuple that describes the target resource of a Web link {{WEB-LINKING}}, or describes the link itself. The value's canonical form is expressed in subset of the data types defined by HTTP Structured Fields {{STRUCTURED-FIELDS}}.
 
-Typically, link hints are serialised in links as target attributes ({{Section 3.4.1 of WEB-LINKING}}).
-
-In JSON-based formats, this can be achieved by simply serialising link hints as an object; for example:
-
-
-~~~ json
-{
-  "_links": {
-    "self": {
-      "href": "/orders/523",
-       "hints": {
-        "allow": ["GET", "POST"],
-        "accept-post": [
-          "application/example+json"
-        ]
-      }
-    }
-  }
-}
-~~~
-
-In other link formats, this requires a mapping from the canonical JSON data model into the constraints of that format. One such mapping is described in {{link_header}} for the Link HTTP header field.
+Typically, link hints are serialised in links as target attributes ({{Section 3.4.1 of WEB-LINKING}}). In the Link HTTP Header, this can be done by serialising those attributes as strings. In other link formats, this requires a mapping from the canonical data model into the constraints of that format.
 
 The information in a link hint SHOULD NOT be considered valid for longer than the freshness lifetime ({{Section 4.2 of HTTP-CACHING}}) of the representation that the link occurred within, and in some cases, it might be valid for a considerably shorter period.
 
@@ -102,89 +82,79 @@ Likewise, the information in a link hint is specific to the link it is attached
 
 * Hint Name: allow
 * Description: Hints the HTTP methods that can be used to interact with the target resource; equivalent to the Allow HTTP response header.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing HTTP methods ({{Section 9 of HTTP}}).
+Content MUST be a Inner List of Strings, containing HTTP methods ({{Section 9 of HTTP}}).
 
 ## formats
 
 * Hint Name: formats
 * Description: Hints the representation type(s) that the target resource can produce and consume, using the GET and PUT (if allowed) methods respectively.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing media types ({{Section 8.3.1 of HTTP}}).
+Content MUST be a Inner List of Strings, containing media types ({{Section 8.3.1 of HTTP}}).
 
 ## accept-post
 
 * Hint Name: accept-post
 * Description: Hints the POST request format(s) that the target resource can consume.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, with the same constraints as for "formats".
+Content MUST be a Inner List of Strings, with the same constraints as for "formats".
 
-When this hint is present, "POST" SHOULD be listed in the "allow" hint.
+When this hint is present, "POST" SHOULD be listed in the "allow" hint when present.
 
 ## accept-patch
 
 * Hint Name: accept-patch
 * Description: Hints the PATCH {{!RFC5789}} request format(s) that the target resource can consume; equivalent to the Accept-Patch HTTP response header.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing media types ({{Section 8.3.1 of HTTP}}) that identify the acceptable patch formats.
+Content MUST be a Inner List of Strings, containing media types ({{Section 8.3.1 of HTTP}}) that identify the acceptable patch formats.
 
-When this hint is present, "PATCH" SHOULD be listed in the "allow" hint.
+When this hint is present, "PATCH" SHOULD be listed in the "allow" hint when present.
 
 ## accept-ranges
 
 * Hint Name: accept-ranges
 * Description: Hints the range-specifier(s) available for the target resource; equivalent to the Accept-Ranges HTTP response header {{HTTP}}.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing HTTP ranges-specifiers ({{Section 14.1.1 of HTTP}}).
+Content MUST be a Inner List of Strings, containing HTTP ranges-specifiers ({{Section 14.1.1 of HTTP}}).
 
 ## accept-prefer
 
 * Hint Name: accept-prefer
 * Description: Hints the preference(s) {{!RFC7240}} that the target resource understands (and might act upon) in requests.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, contain preferences ({{Section 2 of RFC7240}}). Note that, by its nature, a preference can be ignored by the server.
+Content MUST be a Inner List of Strings, containing preferences ({{Section 2 of RFC7240}}). Note that, by its nature, a preference can be ignored by the server.
 
 ## precondition-req
 
 * Hint Name: precondition-req
 * Description: Hints that the target resource requires state-changing requests (e.g., PUT, PATCH) to include a precondition, as per {{Section 13.1 of HTTP}}, to avoid conflicts due to concurrent updates.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, with possible values "etag" and "last-modified" indicating type of precondition expected.
+Content MUST be a Inner List of Strings, with possible values "etag" and "last-modified" indicating type of precondition expected.
 
 See also the 428 Precondition Required status code ({{!RFC6585}}).
 
 ## auth-schemes
 
 * Hint Name: auth-schemes
 * Description: Hints that the target resource requires authentication using the HTTP Authentication framework {{Section 11 of HTTP}}.
-* Content Model: array (of strings)
+* Content Model: Inner List of Strings
 * Specification: \[this document]
 
-Content MUST be an array of strings, each corresponding to a HTTP authentication scheme ({{Section 11.1 of HTTP}}), and optionally a "realms" member containing an array of zero to many strings that identify protection spaces that the resource is a member of.
-
-For example:
-
-~~~ json
-  {
-    "auth-schemes": [
-      "Basic", "Digest"
-    ]
-  }
-~~~
+Content MUST be a Inner List of Strings, each corresponding to a HTTP authentication scheme ({{Section 11.1 of HTTP}}), and optionally a "realms" member containing an array of zero to many strings that identify protection spaces that the resource is a member of.
 
 ## auth-realms
 
@@ -195,27 +165,17 @@ For example:
 
 Content MUST be an array of strings, each indicating a protection space that the resource is a member of.
 
-For example:
-
-~~~ json
-  {
-    "auth-realms": [
-      "private"
-    ]
-  }
-~~~
-
 ## status
 
 * Hint Name: status
 * Description: Hints the status of the target resource.
-* Content Model: string
+* Content Model: Token
 * Specification: \[this document]
 
-Content MUST be a string; possible values are:
+Content MUST be a Token; possible values are:
 
-* "deprecated" - indicates that use of the resource is not recommended, but it is still available.
-* "gone" - indicates that the resource is no longer available; i.e., it will return a 410 (Gone) HTTP status code if accessed.
+* deprecated - indicates that use of the resource is not recommended, but it is still available.
+* gone - indicates that the resource is no longer available; i.e., it will return a 410 (Gone) HTTP status code if accessed.
 
 
 
@@ -234,65 +194,25 @@ Link hints are generic; that is, they are potentially applicable to any HTTP res
 
 Hint names MUST be composed of the lowercase letters (a-z), digits (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a lowercase letter.
 
-Hint content MUST be described in terms of JSON values ({{Section 3 of JSON}}).
+Hint content MUST be described using valid combinations of the following types defined by HTTP Structured Fields ({{STRUCTURED-FIELDS}}):
+
+* Inner List ({{Section 3.1.2 of STRUCTURED-FIELDS}})
+* Item ({{Section 3.3 of STRUCTURED-FIELDS}})
 
 Hint semantics SHOULD be described in terms of the framework defined in {{WEB-LINKING}}.
 
 New hints are registered using the Expert Review process described in {{?RFC8126}} to enforce the criteria above. Requests for registration of new resource hints are to use the following template:
 
 * Hint Name: \[hint name]
 * Description: \[a short description of the hint's semantics]
-* Content Model: \[valid JSON value types; see RFC627 Section 2.1]
+* Content Model: \[allowed Structured Fields types]
 * Specification: \[reference to specification document]
 
 Initial registrations are enumerated in {{hints}}. The "rel", "rev", "hreflang", "media", "title", and "type" hint names are reserved, so as to avoid potential clashes with link serialisations.
 
 
 --- back
 
-# Representing Link Hints in Link Headers {#link_header}
-
-A link hint can be represented in a Link header ({{Section 3 of WEB-LINKING}}) as a link-extension.
-
-When doing so, the JSON of the hint's content SHOULD be normalised to reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are part of a string value, these characters MUST be escaped as described in {{Section 7 of JSON}}; otherwise, they MUST be discarded.
-
-Furthermore, if the content is an array or an object, the surrounding delimiters MUST be removed before serialisation. In other words, the outermost object or array is represented without the braces ("{}") or brackets ("[]") respectively, but this does not apply to inner objects or arrays.
-
-For example, the two JSON values below are those of the fictitious "example" and "example1" hints, respectively:
-
-~~~
-"The Example Value"
-1.2
-~~~
-
-In a Link header, they would be serialised as:
-
-~~~ http-message
-Link: </>; rel="sample"; example="The Example Value";
-      example1=1.2
-~~~
-
-A more complex, single value for "example":
-
-~~~ json
-[
-  "foo",
-  -1.23,
-  true,
-  ["charlie", "bennet"],
-  {"cat": "thor"},
-  false
-]
-~~~
-
-would be serialised as:
-
-~~~ http-message
-Link: </>; rel="sample"; example="\"foo\", -1.23, true,
-      [\"charlie\", \"bennet\"], {"cat": \"thor\"}, false"
-~~~
-
-
 
 # Acknowledgements