Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
hrennau opened this issue Jan 12, 2020 · 13 comments
Open
Assignees
Labels
clarification Items that need to be clarified in the specification core

Comments

@hrennau
Copy link

hrennau commented Jan 12, 2020

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
Copy link
Member

@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
Copy link
Contributor

@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
Copy link
Member

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?

@handrews handrews self-assigned this Feb 13, 2020
@awwright
Copy link
Member

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
Copy link
Contributor

handrews commented Feb 24, 2020

@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
Copy link
Contributor

dret commented Feb 24, 2020 via email

@awwright
Copy link
Member

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

@darrelmiller
Copy link

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
Copy link
Contributor

dret commented Oct 15, 2020 via email

@awwright
Copy link
Member

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.

@Relequestual Relequestual assigned awwright and unassigned handrews Oct 20, 2020
@awwright
Copy link
Member

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
Copy link
Member

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

@Relequestual
Copy link
Member

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

@gregsdennis gregsdennis added clarification Items that need to be clarified in the specification and removed feedback labels Jul 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification Items that need to be clarified in the specification core
Projects
None yet
Development

No branches or pull requests

7 participants