using/defining the "schema" link relation type

[dret]

it seems that -07 recommends using schema-typed links (as one method) to link an instance to a schema. this link relation is not registered (yet). this means either there should be some spec doing this, or maybe the JSON schema draft should do it. if the latter and you need some help, let me know.

[handrews]

@dret thanks! Yes, we were planning to register it as part of the JSON Schema draft. Or motivated by the JSON Schema draft, or whatever the appropriate mental model is. But I have no idea what approach is likely to be successful, and any advice would be appreciated.

Should we try to register it now, or is that something that must wait until we're at RFC or at least adopted by a working group?

[handrews]

I almost put in an extension link relation like tag:json-schema.org,19-11-2017:schema or something, but that seemed more likely to confuse people, and then folks would have to change it again if/when we got the link relation registered.

[dret]

definitely never ever put identifiers in specs and then change them. that’s the X- disaster all over again...

…

On Dec 19, 2017, at 19:32, Henry Andrews ***@***.***> wrote: I almost put in an extension link relation like tag:json-schema.org,19-11-2017:schema or something, but that seemed more likely to confuse people, and then folks would have to change it again if/when we got the link relation registered. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[handrews]

definitely never ever put identifiers in specs and then change them. that’s the X- disaster all over again...

Hah! Yeah, makes sense. We only changed from "profile" to "schema" due to the discussions here that "profile" really wasn't quite right. Given that "schema" is a pretty common concept applying to many media types, it seems like a good candidate for link relation / media type parameter.

I did just see dret/I-D#92 about maybe using HTTP Prefer or some other proposal instead / in addition to media type parameters for "profile", so I'd be interested in considering similar options for "schema" if that makes sense.

I see "profile" and "schema" as similar, but while "profile" identifies a broadly applicable subset, "schema" identifies a set of values suitable for a much more specific purpose. It can also identify something broad, but the ability to be specific is what (I think) distinguishes it.

[dret]

On 2017-12-19 19:31, Henry Andrews wrote: @dret <https://github.com/dret> thanks! Yes, we were planning to register it as part of the JSON Schema draft. Or motivated by the JSON Schema draft, or whatever the appropriate mental model is. But I have no idea what approach is likely to be successful, and any advice would be appreciated.

writing up a draft of its own may be a bit much. it would have the advantage of being more visible, and not creating the impression that "schema" is for JSON only. but it's perfectly fine to leave it in there and make it part of the draft's IANA considerations. the only advice i have is to create a section for it that defines and describes it, and that is very careful at making it independent of JSON schema. that way, anybody interested in the definition could just read that section and wouldn't have to dive into the rest of the spec.

Should we try to register it now, or is that something that must wait until we're at RFC or at least adopted by a working group?

process-wise, if you want to register it now, a separate draft is the best way to go (it's not the only way, as there is no formal requirement that only RFCs can register link relation types). you can also leave it in there and then formally speaking, it would only become registered once JSON schema becomes an RFC. while the IANA registry is only updated after RFC status, at http://webconcepts.info/concepts/link-relation/ i am compiling quite a number of link relation types that are defined in drafts. the reason is that these often are already in use, so keeping them "under wraps" probably is less useful than telling people that these are things that are under consideration/development. it is then up to them to decide whether they already want to get on board, or wait for the official registry to be updated.

[dret]

On 2017-12-19 20:33, Henry Andrews wrote: Hah! Yeah, makes sense. We only changed from "profile" to "schema" due to the discussions here that "profile" really wasn't quite right. Given that "schema" is a pretty common concept applying to many media types, it seems like a good candidate for link relation / media type parameter.

it certainly has popped up quite often, in a variety of communities. i am not quite sure what the best word is. some communities might call this a vocabulary or an ontology, but it may be hard to find a word that works perfectly for everybody.

I did just see dret/I-D#92 <dret/I-D#92> about maybe using HTTP |Prefer| or some other proposal instead / in addition to media type parameters for "profile", so I'd be interested in considering similar options for "schema" if that makes sense.

i am not sure that it makes the same sense. a profile is an additional "layer" of constraints on top of a schema, so to speak. it is always safe to ignore it, because the baseline always is the schema (i.e., the media type). for complex scenarios, you might need something more complex, such as the `Profile` header proposal (which to my mind uses the term "profile" in a rather different way from RFC 6906 anyway and to some extent simply may be actually a schema negotiation proposal).

I see "profile" and "schema" as similar, but while "profile" identifies a broadly applicable subset, "schema" identifies a set of values suitable for a much more specific purpose. It can also identify something broad, but the ability to be specific is what (I think) distinguishes it.

a schema sets the basics in how to represent concepts. if you cannot agree on a schema (which to me is nothing but the implementation of a domain model), then there is no mutual understanding. a profile assumes that there is a baseline, and the profile is an optional layer of conventions. it should always be safe to go back to the baseline and still have the mutual understanding established by that baseline. (that's pretty much the atom example from the profile spec)

[handrews]

a schema sets the basics in how to represent concepts

This seems like a good key distinction: the schema is about representation. You may have different valid and useful representations of an abstract type (which might clarify the distinction between "type", registered as describing the "abstract semantic type") vs "schema" (describing a particular way to represent that type in a data model, which may then be encoded in one or more media types).

So you could potentially negotiate both the schema (describing the data model for a representation) and media type (the concrete encoding of that data model into a JSON/YAML/XML/whatever document).

[dret]

On 2017-12-30 11:35, Henry Andrews wrote: So you could potentially negotiate both the schema (describing the data model for a representation) and media type (the concrete encoding of that data model into a JSON/YAML/XML/whatever document).

at least for my terminology this is not how i think about schemas. schemas are defining models and their representation, let's say an XML model in terms of how it is represented in XML concepts. that tells you everything you need to know in terms of how this will look on the wire. same for JSON schemas. for me, RDF is the outlier here because as an exception to the usual way how people use media types. RDF is an abstract model and you need to know a media type to determine how to serialize it. but the general idea that cultivating a zoo of model serializations is a good thing is more the exception than the rule. one way or the other, i would be clear about how you use these terms, and if possible try to align them with "standard usage". but of course that's not a super well-defined concept to begin with...

[handrews]

schemas are defining models and their representation, let's say an XML
model in terms of how it is represented in XML concepts. that tells you
everything you need to know in terms of how this will look on the wire.
same for JSON schemas.

JSON Schemas work on a data model that is derived from but not specific to JSON. This is why I view the schema and media type as separate. JSON Schema keeps them separate, and the expectation is that people may use JSON, JSON5, YAML, TOML, CBOR, Protobuf, whatever with them. Some of those are a better fit than other, but the extensibility of JSON Schema allows for describing concepts more precise than can be directly expressed in the data model. You could probably make it work for XML to some degree, but I can't imagine why anyone would.

So the data model and media type are not entirely separate, but they are definitely not identical. Any definition of "schema" that requires them to be would be problematic for JSON Schema.

[dret]

On 2017-12-30 12:00, Henry Andrews wrote: JSON Schemas work on a data model <https://tools.ietf.org/html/draft-handrews-json-schema-00#section-4.2.1> that is derived from but not specific to JSON. This is why I view the schema and media type as separate. JSON Schema keeps them separate, and the expectation is that people may use JSON, JSON5, YAML, TOML, CBOR, Protobuf, whatever with them. Some of those are a better fit than other, but the extensibility of JSON Schema allows for describing concepts more precise than can be directly expressed in the data model. You could probably make it work for XML to some degree, but I can't imagine why anyone would.

interesting info, thanks. so it's more "JDM" (keeping in line with the XDM) than actually strictly "JSON schema". that makes sense as for example XSD also technically is an XDM schema language. it's just that nobody ever cared (much) because XML is the only relevant serialization out there. it's just that in my mind, when you go this route, this recurring idea of being able to indicate a "model" to me terminologically makes more sense than the term "schema", but that's really just a question of how people typically use these terms in their own scenarios. (and of course you could argue that "model" is too abstract and that you could have multiple schemas for the same model, which of course is true. it's complicated. ;-)

So the data model and media type are not entirely separate, but they are definitely not identical. Any definition of "schema" that requires them to be would be problematic for JSON Schema.

ok, fair enough. i would just make all of this explicit so that people understand the terms and how they are used in that context.

[handrews]

Thanks, @dret this discussion is very helpful.

It's definitely occurred to me that "schema" is not necessarily the best name for JSON Schema, particularly given that people use it for so many things including data model definitions (code generation, doc generation, ui generation) to the extent that we are looking at adding vocabularies specifically for those purposes.

Then again, the project's been called JSON Schema for many years, and changing the name would likely kill any momentum of the larger ecosystem, so... ¯\(ツ)/¯

[awwright]

I was only casually paying attention, but I wasn't actually aware the specification changed the link relation we were using. No existing link relation was sufficient?

• "profile"
• "describedBy"
• "type"

For example

Link: <http://example.org/Person.schema.json>; rel="type"; type="application/schema+json"

https://tools.ietf.org/html/rfc5988 (HTTP Link header, including description of the "type" attribute)
https://tools.ietf.org/html/rfc6906 (rel="profile")
https://tools.ietf.org/html/rfc6903 (various relation types including rel="type")

I know @dret suggested "profile" was incorrect for us but my reading of RFC6906 suggests we were using it exactly correctly. Perhaps I wasn't describing what we're intending to do very clearly?

[handrews]

@awwright duuuuuuuuude....

• Here is the PR on which I requested a review from you, tagged you in the issue comments, and held it open for an extra 2.5 weeks beyond the usual 2 week period specifically trying to get a review from you. By name.
• Here is the issue in which you and I discussed the "profile" relationship extensively with @dret. You even assigned the issue to yourself when I posted that PR, and then didn't comment on it for over a month.

At some point, I can't keep waiting. I know I pinged you on email and slack because I know you are interested in this area. This is the 2nd time in the past month that someone has wanted to revisit something that I begged and pleaded for comments on. I don't know what to do when people won't reply in any meaningful way for over a month. I try direct email, @-mentions, mailing list, IRC, slack, anything and everything I can think of. I announced the final review period everywhere, often repeatedly, and it was open for a solid month. I did everything I could think of. In all seriousness, what am I missing? What do people need in order to make a timely review before publication? Or at least skim the change log, which lists this change?

Regarding "profile", if you want to keep arguing with @dret about it go ahead, but I found his reasoning quite clear and see no reason to revisit it. I don't know how you read him clearly stating that schemas are not profiles and come to a different conclusion.

You also cited HTML's "profile" , which does seem much closer to what we would want, but the response to that is that just because HTML uses the same word, that does not mean that it is using it in the RFC 6906 sense, and you never replied to that concern (or made any further replies on the issue at all for the remaining ten months that it was open).

There is also the Accept-Profile proposal which is specifically using a different definition of profile than RFC 6906. So I suppose we could define our own "profile" definition, but since we're talking about a media type parameter and link relation, unlike with HTTP headers, that term is already in use. We can't just re-define it to agree with some other definition somewhere else that suits us better.

Regarding "type", as far as I can tell we both agreed that it was not quite right. It is specified to identify the "abstract semantic type", which is a more generic concept. If I identify something's "type" as "car", there may be numerous schemas that describe different ways of representing a car. In particular, as the representation evolves, new schema versions will be published and used, but the "abstract semantic type" remains the same.

So I see "type" as serving a clear purpose of abstracting away concrete representation details, while the relation we need is specifically about concrete representation.

As for "describedBy", it's still in the spec and still doing exactly what it was doing before. Although I'm not actually sure we should continue using it. AFAICT it is more often used for things like human-readable documentation, which would be useful alongside of schema links. We were also using it because "profile" is specifically an identifier and not a locator, so "describedBy" was to be the locator. But we could define things differently with our own media type parameter / link relation if we want. I'm definitely not dead-set on getting rid of it, but once we settle on the behavior we want from our own relation type we should make sure our usage still makes sense.

[awwright]

@handrews Actually I do remember a lot of that now that you mention it.

Have we pinged @RubenVerborgh to get his take on how/if his usage is similar to ours & RFC 6906?

Edit: Yeah you did that too, nice.

Edit: My reading of rel="type" is that it's extremely generic:

The "type" link relation references the payload's abstract semantic type
[...]
If the context can be considered to be an instance of multiple semantic types, multiple "type" link relations can be used.

So while something more specific would be preferable, but I still think could be relevant