Add custom headers for meta-schemas

[jdesrosiers]

Resolves #199

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	0b6aef0
Status:	✅  Deploy successful!
Preview URL:	https://ef9b8fdf.website-2v2.pages.dev
Branch Preview URL:	https://meta-schema-headers.website-2v2.pages.dev

View logs

[jdesrosiers]

It appears that Cloudflare is having issues deploying the preview. I don't believe there's any way to test these changes other than with the preview.

[Relequestual]

The deploy seems to have worked now, but it doesn't work.
The docs say...

You may only include a single splat in the URL.

May have to list out the drafts. OR, we may be able to use placeholders for the last part of the path.

[Relequestual]

Per above comment. Does not seem to work. Cann't use multiple splats.

[jdesrosiers]

It worked! 🎉

[benjagm]

Thanks a lot for this great work. Just left a small suggestion to cover a missing case.

[benjagm]

Suggested change

	/draft/:draft/output/*schema
	/draft/:draft/output/*

I'll suggest this modification to cover "/draft/2019-09/output/verbose-example" and "/draft/2020-12/output/verbose-example"

[jdesrosiers]

"verbose-example" doesn't belong because it's not a schema. It's example output for the verbose output format.

[Relequestual]

Given the recent plan/agreement to modify the meta-schemas to remove unused/nonsensical use of $vocabulary, is marking them immutable in cache control the right thing?
I'm not overly familiar with cache control headers, and I couldn't ascertain from reading docs if I felt it was right for this or not.

[jdesrosiers]

is marking them immutable in cache control the right thing?

"immutable" tells caches not to request the resource while the cached version is still fresh. It's not forever. in this case, "max-age" determines how long the cache should consider the resource "fresh". If we want to account for changes to the schema, we can make "max-age" smaller. Perhaps a week or a month is appropriate.

[benjagm]

Please, let's use the recommendation for non-breaking changes I added in this proposal for deprecation process.

[jdesrosiers]

@benjagm, should I take a stab at writing up the announcement, or do you want to do that?

[benjagm]

@benjagm, should I take a stab at writing up the announcement, or do you want to do that?

If you can start with it, that would be great. Thanks!

[jdesrosiers]

@Relequestual

is marking them immutable in cache control the right thing?

"immutable" tells caches not to request the resource while the cached version is still fresh. It's not forever. in this case, "max-age" determines how long the cache should consider the resource "fresh". If we want to account for changes to the schema, we can make "max-age" smaller. Perhaps a week or a month is appropriate.

On further thought, I do think a very long cache is appropriate. Changes to meta-schemas are rare, especially for older versions. When they do happen, it's to fix a bug in a recently released version. We don't have anything in that category right now. I think it's reasonable to have a shorter cache for a new release, but that's not necessary for anything we have now.

This recent change is unusual in that I don't think we've ever changed a meta-schema just to do some inconsequential cleanup and I don't expect it's likely to happen often, if ever again. But if it does happen, it's not a big deal if people have the old version cached because the only thing that changed was cosmetic. We would never change the behavior of a released meta-schema, so there's no practical difference between the old and the new. If for some reason there is a change where something is broken in the old version, the new version can be retrieved by either clearing cache or sending a Cache-Control: no-cache request header.

[jdesrosiers]

@benjagm, how's this? I think we should get the announcement out ASAP since there's such a long lead time before we can actually merge.

We're making a slight change to the way we serve meta-schemas. In the past our website hosting situation has limited us from serving meta-schemas with the proper headers. With the release of the new website, we now have the opportunity to improve that situation.

What is changing?

• Meta-schemas will now be served with Content-Type: application/schema+json
• Meta-schemas will be served with Cache-Control headers that instruct HTTP caches to cache them
• Meta-schemas will be accessible using CORS

What do you need to do?

We don't expect this change to effect anything you're currently doing with meta-schemas. It only enables more things you could do with them. If you make HTTP requests to fetch the official meta-schemas in your implementation or application, please make use of the new cache headers to properly cache those requests.

When is this change coming into effect?

[benjagm]

how's this?

This is perfect. I'll send it today.

[benjagm]

The announcement is out:

• https://github.com/orgs/json-schema-org/discussions/525
• https://json-schema.slack.com/archives/C01UAR49N0M/p1699607606556049