Link relation for pointing to network-addressable schema

[awwright]

JSON Schema presently specifies to use the "profile" link relation, e.g.:

Link: <http://example.com/Schema.json>;rel="profile"

However, the "profile" link relation is not supposed to be dereferenced. There's no way for an automated user agent to be able to follow this link and actually download the schema if it doesn't already have it.

Perhaps publish a link relation type, similar to profile, that is supposed to be downloaded?

[handrews]

From RFC 6906:

Thus, clients SHOULD treat profile URIs as
identifiers and not as links, but profiles MAY be defined in a way
that the URIs do identify retrievable profile description and thus
can be accessed by clients by dereferencing the profile URI. For
profiles intended for use in environments where clients may encounter
unknown profile URIs, profile maintainers SHOULD consider to make the
profile URI dereferencable and provide useful documentation at that
URI. The design and representation of such profile descriptions,
however, is outside the scope of this specification.

Which I take to mean that a client cannot depend on a profile URI being a dereferencable, but as profile authors are encourage to provide a derferencable URI for the profile then it certainly can be dereferenced and used. It's just not guaranteed to be dereferencable.

So I think the only problem here is that it's not something anyone can rely on, but it is valid for it to work the way the json-schema specification suggests.

Plus, json-schema also provides for use of the describedBy link relation type, so isn't this effectively already fixed? The describedBy relation is explicitly dereferencable.

[awwright]

Take a look at what I wrote for the new JSON Schema website yesterday:
https://awwright.github.io/json-schema-org-pages/guide/http

Does this mesh well with everyone's understanding?

On Sep 10, 2016 4:06 PM, "Henry Andrews" notifications@github.com wrote:

From RFC 6906:

Thus, clients SHOULD treat profile URIs as
identifiers and not as links, but profiles MAY be defined in a way
that the URIs do identify retrievable profile description and thus
can be accessed by clients by dereferencing the profile URI. For
profiles intended for use in environments where clients may encounter
unknown profile URIs, profile maintainers SHOULD consider to make the
profile URI dereferencable and provide useful documentation at that
URI. The design and representation of such profile descriptions,
however, is outside the scope of this specification.

Which I take to mean that a client cannot depend on a profile URI being a
dereferencable, but as profile authors are encourage to provide a
derferencable URI for the profile then it certainly can be dereferenced and
used. It's just not guaranteed to be dereferencable.

So I think the only problem here is that it's not something anyone can
rely on, but it is valid for it to work the way the json-schema
specification suggests.

Plus, json-schema also provides for use of the describedBy link relation
type, so isn't this effectively already fixed? The describedBy relation is
explicitly dereferencable.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#9 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAatDYB68oeEOHg7eLY-iUtLWxeltWoeks5qozf7gaJpZM4G35Y_
.

[handrews]

Thanks for the quick reply! The new site looks great, btw.

This paragraph does not match my reading of the RFC

The “profile” media-type parameter is never supposed to be dereferenced or used to download a schema, it is strictly an identifier provided for the benefit of clients that have pre-programmed knowledge of what that profile means.

although I am certainly open to being convinced that my reading is wrong. A revision of this paragraph that fits my (current) understanding would be something like:

The “profile” media-type parameter is an identifier provided for the benefit of clients, and while it is a URI is not guaranteed to be dereferencable or to result in a downloadable schema. However, implementations MAY provide a downloadable schema at the profile URI. To unambiguously provide a downloadable URI, use the describedBy header.

(this probably needs rewording to be stylistically consistent, but hopefully you get the idea)

In practical terms, I think implementations should supply both. The profile is important for fully understanding the media type, which should be the authority for understanding how to handle the content. The describedBy link relation guarantees a downloadable form.

A particularly interesting use case (relevant to some past work of mine) is having a standard identifier URI in the profile field (for instance, a URI hosted on the provider's primary web site), while putting a local downloadable URI in the describedBy link (for instance, a local copy on the appliance providing the REST service).

This way if the identifying URI is not available (due to the configuration of the network containing both the appliance implementing the API and the client system using the API), the client can download a usable schema from any one of several appliances, but know from the profile URI that those schemas are identical no matter which appliance is involved.

[handrews]

I think my point here is actually a rather small one- I agree with what you wrote about how things should work, I just think that, in the absence of a describedBy link, the profile RFC allows that an implementation may attempt to de-reference the profile URI.

I'm not sure how important this distinction really is, I just feel like the current wording imposes additional restrictions on top of the profile RFC. Which may be what we want in order to encourage use of describedBy?

[awwright]

I fixed links so navigation should work now...

I forget if "profile" as a media-type parameter is actually defined in any RFC, I recall it is, for other media types (not application/json or even application/* or /). Is there one you're aware of?

RFC 6906 defines the "profile" link relation, which says it shouldn't ever be dereferenced, it's just an identifier.

The current JSON Schema draft is mostly silent on the matter.

I'd definitely say that a JSON Schema should be downloadable at the profile URL as a human convenience, though.

[handrews]

Where do you see that RFC 6906 says never? Again, this is the part I'm reading (section 3, paragraph 3):

Thus, clients SHOULD treat profile URIs as identifiers and not as links, but profiles MAY be defined in a way that the URIs do identify retrievable profile description and thus can be accessed by clients by dereferencing the profile URI.

That is a SHOULD and not a MUST, and there is a MAY that specifically says that clients can try to dereference it because it MAY function as a link. That does not say "never" to me.

I think what it does say is pretty weird- basically "it's not a link, except that it might be so go ahead and try it." If they're going to have that MAY in there it kinda undermines the point of the SHOULD. But it's there, so clients can try it.

To me, the difference between profile and describedBy is that profile must identify the schema, and therefore must be the same URI in every response or request that is an instance of that schema. And that URI need not be dereferencable, although it might be. On the other hand, describedBy just needs to be a dereferencable URL that yields the schema. It might be a different URL every time. (technically the mini-spec says URI so it might not be dereferencable, but I don't see much point in a non-dereferencable describedBy as the mini-spec does not say that the URI is a unique identifier for the describing resource)

TL;DR:
profile == identification
describedBy == location

[handrews]

Oh and RFC 6906 also describes the media type parameter usage- it's in section 3.1.

[jdesrosiers]

I've always liked describedBy as a correlation mechanism better than profile even though I seemed to be in the minority. But, I want to point out that the new website does contradict the wording in the current spec.

It is RECOMMENDED that a MIME type parameter by the name of "profile" be appended to the "Content-Type" header of the instance being processed. If present, the value of this parameter MUST be a valid URI, and this URI SHOULD resolve to a valid JSON Schema.

The new wording is more of a correction than a change, but whether it is a bug or not, many people currently rely on profile as being dereferenceable. Is the new website intended to be a cleaned up version of Draft 04 or is it intended to be a new draft? If it's a new draft, there's no problem. If it's supposed to be Draft 04, we should be wary of contradicting the current specification.

If @handrews's, wording is used, it doesn't contradict Draft 04. It just loosens the requirement from SHOULD to May. However, even though this wording is probably more technically correct, if this is a new draft, the benefit of the stronger wording that @awwright has used is that it will discourage people from misusing profile when describedBy is a more appropriate choice. Probably something in between is best; an accurate description of profile as well as some strong wording telling people to use describedBy if they expect user agents to dereference the URI.

[handrews]

@jdesrosiers I'm not so much trying to loosen anything as get the JSON Schema standard's wording to match RFC 6906, OR clearly state that JSON Schema is layering additional restrictions on top of RFC 6906.

I think it's critically important to specify both profile and describedBy and be clear about their intended use. As noted, at my last job we had the situation of numerous appliances (each hosting an API instance, including self-hosting (describedBy) the appropriate schemas) that were firewalled off from the internet at large, which is where the canonical URI (profile) for each schema pointed.

Without profile, there would be no guarantee that a client talking to resource A on appliance X could use the same schema when talking to resource A on appliance Y, even if the describedBy URIs on X and Y looked the same aside from the hostnames. But without describedBy, the client would not be able to download the schema even though a downloadable schema existed at the profile URI, because the network configuration prevented connecting to that URI.

Aside from being clear about either allowing but discouraging attempts to dereference profile as laid out in RFC 6906, I think the only change I'd like to see on the page on the new web site is a clarification of why you would want to use both. Otherwise, it's a bit unclear why profile is involved. It does make the media type more complete but that's a relatively obscure bit of philosophy to a lot of people.

[awwright]

Also refer to very similar issue #26 "Profiles are not schemas"

So it seems we just need to nail down which level of language do we use to permit/restrict clients dereferencing which URIs... but it seems we've mostly settled on the purpose of "profile" vs. "describedby" and @handrews type of use-case is particularly the reason why the distinction exists.

Let's start figuring out what we can add to the spec that we know for sure, first:

JSON Schema isn't actually using RFC 6906 normatively in any capacity:

• It's not using the "profile" link relation (or doesn't require use of it)
• It's not registering a "profile" media type parameter (that's what we're going to do for application/json)

But let's add it as an informative/non-normative reference, at the very least. Thanks for the find @handrews

We also need to add normative references for the "describedby" link relation: to POWDER and/or, preferably, LDP.

[jdesrosiers]

@handrews, I get what you are trying to do and I agree with where you and @awwright are going with this. The contribution I was trying to make is that we need to be careful about changing the meaning of profile as it is defined in Draft 04. A lot of code has been written to conform to that definition. If we now say profile means something different, all of that code no longer conforms to the specification.

[handrews]

@jdesrosiers I think that's a very valid concern, but somewhat orthogonal to determining the long-term correct behavior. I'm a little fuzzy on whether we're talking about a bug fix to draft 04 or a change targeted at draft 05.

For a bug fix to draft 04 (or a draft 05 that is intentionally a minimal update), I would add the RFC 6906-conforming language, but include a bit about how, for historical reasons, API designers are strongly encouraged to use a resolvable URI even though the RFC is not particularly encouraging on that point. That should make it clear enough that draft 04 users who do not do that risk encountering problems with existing draft 04 tooling, and they can make up their mind whether they're OK with that or not. But I think it's important to get the correct use cases and recommendations into the spec somehow.

For a change to draft 05 (or draft 06 if 05 is minimal update), I would be inclined to wait and see how much breakage there ends up being for moving to the new version. It may be that relaxing the dereferencability of the profile is a minor item compared to other changes. Or we may want to preserve the advisory note about encouraging dereferencable profiles.

Does that sound reasonable? There are going to be cases, such as the one I gave, where it is simply not possible to have a globally unique profile URI that is dereferencable, so there is a lot of value to having the spec acknowledge that possibility, even if it breaks some tools. Tools are software, after all, and fixing a tool to fall back to describedBy if profile 404s is not hard.

[awwright]

The next Internet-Draft (which we can call draft-05 for now, but will probably be given some other designation by the IETF) is focusing on fixing compatibility problems, updating references to other specifications, adding references where possible, etc.

The website is only a guide for people writing schemas and consuming/producing JSON instances, the authoritative source for behavior is the spec.

The only thing that draft-04 says about "profile" is: 'this URI SHOULD resolve to a valid JSON Schema'

This is weaker language than the "describedby" link, which says: 'The target URI of the "Link" header MUST be a valid JSON Schema'

I think updating all the language around profile vs. describedby falls within this scope, if it's behavior that should already have been expected based on the original definitions (even if not referenced), and if validator implementations aren't obligated to break functionality. I'll link to a PR with specific language here pretty soon...

[awwright]

See also issue #26 "Profiles are not Schemas"