JSON Schema Core - 11.1/11.2 - link relation type "schema" not explained

[hrennau]

JSON Schema Core - 11.2: "HTTP can also send the "schema" in a Link, though this may impact media-type semantics and Content-Type nogotiation if this replaces the media-type parameter entirely: " The statement is followed by an example using link relation type "schema".

Issues Link relation type "schema" has not been mentioned before in the text (which dealt with link relation type "describedby" (11.1) and media type parameter "schema" (11.2)), and the semantics of this link relation type are not explained. Besides, the wording ("... can also send the 'schema' in a Link") does not make it clear that the new paragraph deals with a different link relation type, hitherto not considered. Rather, the text seems to only point at consequences of leaving out the media-type parameter.

Or perhaps the use of link relationship type "schema" is an error and should be replaced by "describedby"?

[Relequestual]

@handrews @awwright What do yous want to do here? The CREF makes it sound like this paragraph was tagged on with a hope and a wish that we would go define the rel type schema at some point maybe.

Till such a time, should we just remove it? Given that we've already said to use describedby, I'm not sure what schema would offer that's different.

[handrews]

@Relequestual schema replaced the use of profile in earlier drafts, since @dret (who wrote the profile RFC) said we were using it wrong. Although as far as I can tell lots of projects use it wrong and just ignore what the RFC actually says, which I personally find immensely frustrating even though it's not my RFC :-/

The idea is that schema provides the canonical URI (the one that would show up in the root $id of the resource) while describedby provides a usable URL for retrieval. The describedby URL might be one involving a fragment if multiple resources have been packed into a single document for distribution. Or, in the case of an appliance deployed behind a firewall that prevents reaching the canonical URI, the describedby URL might be hosted on the appliance.

There used to be language to this effect somewhere in the spec, I guess it got dropped in one of the edits?

[Relequestual]

What I read by this is that... The difference is schema is like $id, it's the canonical URI, but may not be network addressable, while a describedby SHOULD be network addressable and the application should attempt to retrieve it?

[awwright]

I still maintain we were using "profile" correctly:

A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms.

If this isn't what a JSON Schema does to JSON documents, I'd like to ask what does it do? JSON Schema does not alter the semantics of JSON, but allows clients to learn additional semantics (constraints) associated with the resource.

The problem (if anything) is that the target of rel=profile doesn't necessarily mean the target is a JSON Schema or anything else, and it's unclear how a machine might learn what the profile means, besides being pre-programmed to understand it. However this is true of all link relations, they ought to be media-type agnostic so that other Internet technologies can use them.

---

Agreed on "describedby", it has to be network-accessible. You would use it if the schema URI is a urn: URI, so that you could still provide a way to download that schema.

[handrews]

@awwright you and @dret need to sort this out. I'm tired of being complained to by all sides when y'all won't work it out yourselves.

I personally refuse to contradict the author of a spec when they say that you are using their spec wrong. Primarily because I don't appreciate people insisting on misreading my spec writing.

@dret came here years ago and filed an issue (or commented on one, I forget) [EDIT: it was a comment] saying that we weren't using it right and unless and until you get him to agree otherwise, that's what I'm going with.

[dret]

On 2020-02-24 23:48, Henry Andrews wrote:

@awwright https://github.com/awwright you and @dret https://github.com/dret need to sort this out. I'm tired of being complained to by all sides when y'all won't work it out yourselves.

I personally refuse to contradict the /author of a spec/ when they say that /you are using their spec wrong./ Primarily because I don't appreciate people insisting on misreading my spec writing.

@dret https://github.com/dret came here years ago and filed an issue (or commented on one, I forget) saying that we weren't using it right and unless and until you get him to agree otherwise, that's what I'm going with.

i am still seeing a difference, but i am also tired of arguing. and i am thinking that once you release something into the wild, it kind of isn't entirely your own thing anymore. i have stopped discussing the differences i see a while ago, and that's my policy going forward.

afaict, with what you're doing (or may be doing) you're not breaking anything, so i think that if you decide to go that way, nothing bad will happen. that's already quite something, right? godspeed!

[awwright]

Sorry I didn't intend to be argumentative. I don't understand what the counterpoint is very well, and I would like to.

[darrelmiller]

The distinction I see is that having a JSON schema could say a property called "age" must be a number and greater than 18. But that is not defining the semantics of "age". A profile provides an identifier that is shared knowledge between client and server and ensures that client and server agrees that the "age" property contains a number that represents how many years a thing has existed.

My understanding is that with some judicial use of $id, JSON Schema can associate identities to every data element in a JSON payload and therefore could use that $id value as a way of conferring semantic meaning to properties.

I don't know how far JSON Schema wants to step into the world of JSON-LD. If being an identifier of semantics is one of the goals of JSON Schema, I can see how it could be used as a profile. But is that really how most people use JSON Schema?

I think a schema link relation would be a valuable thing. I can imagine using a schema and a profile at the same time. I could use the schema to confirm the payload has the right "shape and values" and the profile to tell me what it "means".

[dret]

On 2020-10-15 14:35, Darrel wrote:

I think a schema link relation would be a valuable thing. I can imagine using a schema and a profile at the same time. I could use the schema to confirm the payload has the right "shape and values" and the profile to tell me what it "means".

just jumping in here with the usual RFC 6906 comment:

that's not what the RFC 6906 concept of profile is about. but it's a good example to use.

you could have a schema for a person, age being in the range 0-200. then you could have a profile for "adult" that could use the same schema (or a refined one, but that's a different matter) and would only allow age to be 18 and up.

the profile simply allows you to make this distinction: every adult is a person, but you cannot treat every person as an adult.

[awwright]

I would like to propose we think about JSON Schema as a way to define profiles in a machine-readable way. I think this is the primary usage of JSON Schema in hypermedia. To adapt the RFC 6906 Abstract:

A JSON Schema cannot alter the semantics of the JSON media type, but it allows clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the JSON document, in addition to those defined by JSON and other mechanisms.

JSON Schema overloads the term "schema" quite considerably here.

Consider the possibility that the two groups are slightly disjoint, however. It seems plausible to me there are some things that JSON Schema can define that falls outside a "profile", and there are some things that a profile could define, that are not expressible in JSON Schema.

It seems to me both examples could be represented as a JSON Schema. You can have one that describes "Person", and another that describes "Adult", and both may be profiles assigned to a JSON document; and one or both may have a JSON Schema that lets you validate the document.

[awwright]

I think I'll start with an informative section on using JSON Schema to define profiles of JSON documents in a machine-readable way.

But we also need to answer the OP, first I'll double-check the considerations on minting new media types and media type parameters.

[Relequestual]

@awwright If this is likely to be a slow resolution, let's punt it to next draft.

[Relequestual]

Given there appears to be no consensus on this, I'm removing the milestone marker.