json-schema-org / json-hyperschema-spec Goto Github PK

We reference https://tools.ietf.org/html/draft-reschke-http-jfv-07 but it turns out there has been a complex history:

reschke-http-jfv-00 through 04
ietf-httpbis-jfv-00 through 02
then it split, with the JSON work going back to reschke-http-jfv-05 through 07, but the HTTPbis work going forward as an abstract data model for headers in ietf-httpbis-header-structure-00 through 01 (with 02 in the works).

JFV: https://tools.ietf.org/html/draft-reschke-http-jfv-07
Header structure: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-01

We should sort out what is going on here, and also definitively figure out how to address existing headers, particularly those that we recommend using in hyper-schema's targetHints and headerSchema, should be represented.

Now that we can change the context of a link using "anchor" and "anchorPointer", does the following statement from section 8.1 still hold true?

for each target resource and link relation type pair, schema authors SHOULD only define a single LDO.

Using anchors, we can define multiple different links using the same target by changing the context. For (contrived) example, if we're representing links in hierarchical data:

"links": [
  {
    "rel": "up",
    "href": "parent",
    "anchor": "parent/foo"
  },
  {
    "rel": "up",
    "href": "parent",
    "anchor": "parent/bar"
  }
]

As mentioned in the anchor example in section 9.4, using anchor with rel=top is an attractive solution to the lack of an IANA-registered "down" relationship.

While my example seems (to me) like it would be valid, it runs afoul of the "One Link Per Target and Relation Type" rule. Both links have a relationship type of "up" and a target of "parent".

Is the phrasing for section 8.1 a relic from before "anchor" was in the spec? Or am I misunderstanding something about how anchors are supposed to work?

The explanation is probably not correct:

"getApplicableSchemas()" returns an iterable set of all (sub)schemas that apply to the attachment point in the instance.

The use is this:
getApplicableSchemas(ldo.hrefSchema, "/" + varname)

The function use has nothing to do with the attachment point: it extracts from hrefSchema the schema(s) applicable to variable varname. It seems that getApplicableSchemas() should be thought of as a generic function receiving a schema and a JSON pointer and returning the subschemas applicable to the instance value pointed at. Perhaps the explanation should describe this generic functionality, rather than describe the result of its usage.

Document:
https://json-schema.org/draft/2019-09/json-schema-hypermedia.html

Issue: In several places, e.g.
https://json-schema.org/draft/2019-09/json-schema-hypermedia.html#rfc.section.6.1
(section 6.1, first paragraph)

an erroneous reference to the JSON Schema core specification is made:
"Section 3.1 of the JSON Schema core specification)"

The referenced document:
https://tools.ietf.org/html/draft-handrews-json-schema-02

has a section 3, but no section 3.1. This is quite relevant, because the reference is really needed in order to elucidate facts hinted at, but not really explained (e.g. "the link's context resource is, by default, the sub-instance to which it is attached (as defined by ...). This is often not the entire instance document." Interestingly, the term "sub-instance" is not used at all in the core specification, therefore it is not clear what "the sub-instance to which it is attached" means.

While working on the rewrite, it occurred to me that using hrefSchema with a "self" link doesn't make much sense. So I wrote up a bit on how hrefSchema MUST NOT be used with a "self" link, and hrefRequired SHOULD be used to ensure that the self link can always fully resolve from instance data (or if i cannot, it cannot be used).

Then I thought about collections, with filtering and pagination. What does "self" mean in such a case? Strictly speaking, a page of a filtered collection is not the same resource as an unfiltered, unpaginated collection. Or a different page from the same filter, etc. etc. Similar concepts apply to other resources that are logically "modified" or made into a sub-resource by query parameters.

However, there is no inherent distinction between this use of query parameters and a use that produces entirely different resources which are only distinguished by non-hierarchical identifiers.

So if a "self" link MUST NOT use hrefSchema (which is a debatable point), how does a collection or similar resource expose its pagination/filtering/whatever interface for users?

While there are numerous pagination link relations, they should not take user input for the page parameters either. A "first" link must always go to the first page, a "next" link must always go to the next page, whatever that means.

Using a "collection" link alongside of "self" to specify hrefSchema for pagination/filtering/etc doesn't seem to work, as setting the context of "collection" correctly in this scenario is more or less impossible (if there are no items in the collection, then it is entirely impossible).

There is a "search" link relation that has as it's target a description of an interface to search the context. This seems close to what we want, although the target would ideally be the hrefSchema of... um... something? Ugh.. brain hurts. Anyone have ideas on this?

From the Hyper-Schema Security Considerations:

When link relation of "self" is used to denote a full representation of an
object, the user agent SHOULD NOT consider the representation to be the
authoritative representation of the resource denoted by the target URI if
the target URI is not equivalent to or a sub-path of the URI used to request
the resource representation which contains the target URI with the "self"
link.

Does anyone understand the "sub-path" part of this? It seems a bit related to the old pathStart keyword. I can't find anything in RFCs 3986, 4287 (where "self" was first defined), 7230, or 7231 that indicates anything special about URI "sub-path"s, with respect to "self" links or otherwise.

@awwright do you have any idea what this was about? @Julian?

This issue tracks bringing it up to something resembling compliance with RFC 3552: Guidelines for Writing RFC Text on Security Considerations

Originally written by @geraintluff at https://github.com/json-schema/json-schema/wiki/More-templating-(v5-proposal)

Proposed keywords

Uses existing keywords - proposes extension of rel in LDOs.

Other keywords in LDOs could also be subject to this (e.g. mediaType) - however, rel is the most obvious candidate as it is also a URI.

(Yes, in case that was unclear - link relation values are basically all secretly URIs.)

Purpose

Currently, the only property of links that is templated is "href". However, some data formats actually include other link information in the data as well - most often rel (although sometimes others such as media type).

Values

The allowed values would be exactly the same as for href (including the extended templating syntax from issue json-schema-org/json-schema-spec#52 , if applicable).

Behaviour

To obtain the value for the link relation, the value of rel is interpreted in exactly the same way as href.

Concerns

As such, it is probably safe to allow rel to have the same behaviour as href, and this is unlikely to cause incompatability with existing v4 schemas.

If $data makes it into the standard, then we probably don't need to enable templating for anything apart from href and rel - everything else can be referenced wholesale from the data.

In 9.4 Example, the example code says ..

"anchor": "nodes/{thisNodeId}",
"rel": "up",
"href": "nodes/{childId}",

It seems to me it should be the other way around - when the relation is "up", the context (anchor) should be under the target (href) - the context should be the childIds array item, the target should be this object's id.

In the pseudo-code, the call of populateDataFromInstance() should have one more argument, "attachmentPointer", e.g. like this:

template Data = populateDataFromInstance(T, ldo, attachmentPointer, instance)

In general, I suggest to present the three parts of pseudo-code as pseudo-functions - just by inserting the signature above the code - in order to make the required input clearer:

resolveTemplate(T, initialTemplateKeyword, ldo, attachmentPointer, instance)
... (First block of pseudo-code)

populateDataFromInstance(T, ldo, attachmentPointer, instance)
... (Second block of pseudo-code)

acceptInput(T, ldo, templateData)
... (Third block of pseudo-code)

base and links are complex annotations, and the output information should fit in the new output format. So we should explain that. And if it can't be made to fit, we will need to adjust something somewhere.

There are hrefSchema, targetSchema, submissionSchema and own/this {"$ref": "#"} //in draft-07 notation

href is rather clear - more-like HTTP specific channel. While 'target' mostly describes output/return - Event.target, HTMLElement.target, :target vs Proxy.target.

"targetSchema" is used for requests and/or responses for several HTTP methods.

With hyper-media#HTTP, hyper-media#examples, from draft-04 to draft-07 I tried to produce all desired type notation but got lost.

1. GET () => this - for "rel": "next" and similar target is not specified
2. GET () => target
3. PUT (this) => void
4. PUT (this) => target
5. PATCH (target) => void
6. PATCH (target) => this
7. POST (this) => void
8. POST (submission) => target
9. POST (submission) => this
10. DELETE (this | target) => this | void

What points are wrong and what have I lost?

BTW Why links are array? I expected same as $defs - 'keyed' schema collection

• targetMediaType - the media type of the target that this LDO is designed to work with

• schema for HTTP Accept - all of the target media types you can request with HTTP

• submissionMediaType - the media type for constructing the submission request body using this LDO

• hint for HTTP Accept-Post - the possible media types you can use for the request in HTTP

There may be others that I'm not thinking of at the moment. There's no LDO keyword corresponding to Accept-Patch, though, so that's not one.

Section 6.6 Link Input starts with this sentence:

There are four ways to use client input with a link, and each is addressed by a separate link description object keyword.

The keywords referred to are presumably:

• hrefSchema
• headerSchema
• targetSchema
• submissionSchema

I think the sentence is misleading: while hrefSchema is about client input, the other schemas are about interaction with the link, but not about user input.

My suggestion goes beyond editing the sentence, it is a reconsideration of the current structure. A key principle is - and doubtless should be - alignment with the generic link model from RFC 8288. There we have the link property "target attributes", reflected here by section 6.5 Link Target Attributes. It includes 6.5.3. targetMediaType and 6.5.4 targetSchema. All very well.

The issue is that

• 6.6.2 header Schema
• 6.6.4.1. submissionMediatype
• 6.6.4.2. submissionSchema

should also be part of 6.5 Link Target Attributes, as they clearly give information about the target, more precisely, how to interact with it. The contents of

• 6.6.3 Manipulating the Target Resource Representation

finally, might be merged into 6.5.3 and 6.5.4.

How uneasy the current structure is, becomes obvious when trying to relate the sentence quoted in the beginning of this posting ("four ways to use client input ...") to the subsections following it: you would expect four matching subsections, but the third is more like a reference into contents found in 6.5.