Skip to content

Commit 6f7e59e

Browse files
dgebdgeb
authored
Merge pull request json-api#1328 from json-api/1.1
1.1: update site's extensions page + announce release date
2 parents 0f8822b + de11f01 commit 6f7e59e

24 files changed

+1221
-157
lines changed

‎_config.yml

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,24 +13,26 @@ whitelist:
1313
- jekyll-sitemap
1414
- jekyll-feed
1515
- jekyll-seo-tag
16-
- jekyll-gist
1716
- jemoji
1817
incremental: false
1918
gist:
2019
noscript: false
20+
2121
# customize github pages
2222
quiet: false
2323
markdown: kramdown
2424
highlighter: rouge
2525
kramdown:
2626
input: GFM
2727
hard_wrap: false
28-
auto_ids: false
28+
auto_ids: true
29+
auto_id_prefix: auto-id-
30+
auto_id_stripping: true
2931
template: '' # cannot customize
3032
math_engine: mathjax # cannot customize
3133
syntax_highligher: rouge # cannot customize
3234

33-
gems:
35+
plugins:
3436
- jekyll-redirect-from
3537

3638
exclude:
@@ -48,6 +50,9 @@ port: 9876
4850
collections:
4951
format:
5052
output: true
53+
profiles:
54+
output: true
55+
permalink: /:collection/:path
5156

5257
defaults:
5358
- scope:
@@ -57,9 +62,27 @@ defaults:
5762
layout: page
5863
show_sidebar: true
5964
is_spec_page: true
65+
- scope:
66+
path: ""
67+
type: "profiles"
68+
values:
69+
layout: profile_error
70+
is_spec_page: false
71+
show_sidebar: false
72+
- scope:
73+
path: "*/*/*/index.md"
74+
type: "profiles"
75+
values:
76+
layout: profile
77+
is_spec_page: false
78+
show_sidebar: true
6079

6180
latest_version: 1.0
6281
excerpt_separator: ""
82+
announcement: |
83+
**[JSON:API v1.1 RC1](/format/1.1/) has been published!** Please review and
84+
try out this upcoming version of the spec before its planned release date of
85+
January 31, 2019.
6386
6487
navigation:
6588
- title: JSON API
@@ -84,3 +107,12 @@ quicklinks:
84107
url: /format/
85108
- title: Contribute on GitHub
86109
url: https://github.com/json-api/json-api
110+
111+
profile_categories:
112+
- Pagination
113+
# these are some other potential categories.
114+
# Uncomment them if you're adding a profile in one of these categories.
115+
# - Filtering
116+
# - Actions/Hypermedia
117+
# - Data Modeling
118+
# - Deep Querying

‎_format/1.1/index.md

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
---
22
version: 1.1
3+
status: rc
4+
release_date: 2019-01-31
35
---
46

57
## <a href="#introduction" id="introduction" class="headerlink"></a> Introduction
@@ -234,7 +236,7 @@ other and with `type` and `id`. In other words, a resource can not have an
234236
attribute and relationship with the same name, nor can it have an attribute
235237
or relationship named `type` or `id`.
236238

237-
#### <a href="#document-resource-object-attributes" id="document-resource-object-attributes" class="headerlink"></a> Attributes
239+
##### <a href="#document-resource-object-attributes" id="document-resource-object-attributes" class="headerlink"></a> Attributes
238240

239241
The value of the `attributes` key **MUST** be an object (an "attributes
240242
object"). Members of the attributes object ("attributes") represent information
@@ -253,7 +255,7 @@ alongside other information to be represented in a resource object, these keys
253255

254256
> Note: See [fields] and [member names] for more restrictions on this container.
255257
256-
#### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships
258+
##### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships
257259

258260
The value of the `relationships` key **MUST** be an object (a "relationships
259261
object"). Members of the relationships object ("relationships") represent
@@ -285,7 +287,7 @@ data, not the related resources.
285287

286288
> Note: See [fields] and [member names] for more restrictions on this container.
287289
288-
#### <a href="#document-resource-object-related-resource-links" id="document-resource-object-related-resource-links" class="headerlink"></a> Related Resource Links
290+
##### <a href="#document-resource-object-related-resource-links" id="document-resource-object-related-resource-links" class="headerlink"></a> Related Resource Links
289291

290292
A "related resource link" provides access to [resource objects][resource objects] [linked][links]
291293
in a [relationship][relationships]. When fetched, the related resource object(s)
@@ -300,7 +302,7 @@ relationship isn't currently associated with any target resources. Additionally,
300302
a related resource link **MUST NOT** change because its relationship's content
301303
changes.
302304

303-
#### <a href="#document-resource-object-linkage" id="document-resource-object-linkage" class="headerlink"></a> Resource Linkage
305+
##### <a href="#document-resource-object-linkage" id="document-resource-object-linkage" class="headerlink"></a> Resource Linkage
304306

305307
Resource linkage in a [compound document] allows a client to link together all
306308
of the included [resource objects] without having to `GET` any URLs via [links].
@@ -1920,10 +1922,10 @@ request is received, a server **SHOULD** attempt to apply the requested profiles
19201922
to its response.
19211923

19221924
For example, in the following request, the client asks that the server apply the
1923-
`http://jsonapi.org/extensions/last-modified` profile if it is able to.
1925+
`http://example.com/last-modified` profile if it is able to.
19241926

19251927
```http
1926-
Accept: application/vnd.api+json;profile="http://example.com/extensions/last-modified", application/vnd.api+json
1928+
Accept: application/vnd.api+json;profile="http://example.com/last-modified", application/vnd.api+json
19271929
```
19281930

19291931
> Note: The second instance of the JSON:API media type in the example above is
@@ -2257,6 +2259,11 @@ supported as well.
22572259
3. alter the JSON structure of any concept defined in this specification,
22582260
including to allow a superset of JSON structures.
22592261

2262+
2263+
> If you create your own profile, you are **strongly encouraged to [register](/extensions/#profile-registration)
2264+
> it** with the JSON API [profile registry](/extensions/), so that others can
2265+
> find and reuse it.
2266+
22602267
#### <a href="#profiles-updating" id="profiles-updating" class="headerlink"></a> Revising a Profile
22612268

22622269
Profiles **MAY** be revised over time, e.g., to add new capabilities. However,

‎_format/upcoming/index.md

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,8 @@
11
---
2-
is_upcoming_version: true
2+
# Note: We have to do a `redirect_to` here rather than a redirect_from
3+
# in the file for the latest spec version, as the latter causes jekyll
4+
# generate a redirect to `/format/{version}/index.html`, which is an ugly
5+
# and non-canonical url, and jekyll's url config settings aren't flexible
6+
# enough to prevent this.
7+
redirect_to: /format/1.1/
38
---
4-
{% for spec_draft in site.format %}
5-
{% if spec_draft.version > site.latest_version and spec_draft.path contains 'index' %}
6-
{% comment %}
7-
The line below must be outdented (ugly as that is) or it will be parsed
8-
differently, since indentation can be significant in markdown (e.g. to
9-
indicate code blocks).
10-
{% endcomment %}
11-
12-
{{ spec_draft.content }}
13-
14-
{% endif %}
15-
{% endfor %}

‎_includes/global_head_assets.html

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<meta charset="utf-8">
2+
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
3+
<meta name="viewport" content="width=device-width, initial-scale=1">
4+
<link href="/stylesheets/normalize.css" rel="stylesheet" type="text/css" />
5+
<link href="/stylesheets/all.css" rel="stylesheet" type="text/css" />
6+
<link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
7+
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
8+
<script src="/javascripts/all.js" type="text/javascript"></script>
9+
<script src="/javascripts/highlight.pack.js"></script>
10+
<script>hljs.configure({classPrefix: ''}); hljs.initHighlightingOnLoad();</script>
11+
12+
<link rel="apple-touch-icon" sizes="57x57" href="/alt-favicons/apple-touch-icon-57x57.png">
13+
<link rel="apple-touch-icon" sizes="60x60" href="/alt-favicons/apple-touch-icon-60x60.png">
14+
<link rel="apple-touch-icon" sizes="72x72" href="/alt-favicons/apple-touch-icon-72x72.png">
15+
<link rel="apple-touch-icon" sizes="76x76" href="/alt-favicons/apple-touch-icon-76x76.png">
16+
<link rel="apple-touch-icon" sizes="114x114" href="/alt-favicons/apple-touch-icon-114x114.png">
17+
<link rel="apple-touch-icon" sizes="120x120" href="/alt-favicons/apple-touch-icon-120x120.png">
18+
<link rel="apple-touch-icon" sizes="144x144" href="/alt-favicons/apple-touch-icon-144x144.png">
19+
<link rel="apple-touch-icon" sizes="152x152" href="/alt-favicons/apple-touch-icon-152x152.png">
20+
<link rel="apple-touch-icon" sizes="180x180" href="/alt-favicons/apple-touch-icon-180x180.png">
21+
<link rel="icon" type="image/png" href="/alt-favicons/favicon-32x32.png" sizes="32x32">
22+
<link rel="icon" type="image/png" href="/alt-favicons/favicon-194x194.png" sizes="194x194">
23+
<link rel="icon" type="image/png" href="/alt-favicons/favicon-96x96.png" sizes="96x96">
24+
<link rel="icon" type="image/png" href="/alt-favicons/android-chrome-192x192.png" sizes="192x192">
25+
<link rel="icon" type="image/png" href="/alt-favicons/favicon-16x16.png" sizes="16x16">
26+
<link rel="manifest" href="/alt-favicons/manifest.json">
27+
<link rel="mask-icon" href="/alt-favicons/safari-pinned-tab.svg" color="#0b4e22">
28+
<link rel="shortcut icon" href="/favicon.ico">
29+
<meta name="msapplication-TileColor" content="#da532c">
30+
<meta name="msapplication-TileImage" content="/alt-favicons/mstile-144x144.png">
31+
<meta name="msapplication-config" content="/alt-favicons/browserconfig.xml">
32+
<meta name="theme-color" content="#0b4e22">

‎_includes/global_html_footer.html

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<footer>
2+
<div class="site-wrapper">
3+
<span>Built with <a href="https://jekyllrb.com/">Jekyll</a> and <a href="http://softwaremaniacs.org/soft/highlight/en/">Highlight.js</a></span>
4+
<span class="license">
5+
<a rel="license" href="https://creativecommons.org/publicdomain/zero/1.0/"><img src="https://licensebuttons.net/p/zero/1.0/88x31.png" style="border- style: none;" alt="CC0" /></a>
6+
</span>
7+
<span class="social-links">
8+
<a class="twitter" href="https://twitter.com/jsonapi"><i class="icon-twitter"></i><span>Twitter</span></a>
9+
<a class="github" href="https://github.com/json-api"><i class="icon-github"></i><span>GitHub</span></a>
10+
<a class="forum" href="https://discuss.jsonapi.org"><i class="icon-forum"></i><span>Discussion Forum</span></a>
11+
</span>
12+
</div>
13+
</footer>
14+
<script>
15+
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
16+
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
17+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
18+
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
19+
20+
ga('create', 'UA-40609539-1', 'jsonapi.org');
21+
ga('send', 'pageview');
22+
23+
</script>

‎_includes/header_offset_2.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{% comment %}
2+
When we embed the markdown from a user-provided profile specification
3+
inside the profile layout, we need to increment each heading level by 2.
4+
Kramdown, our markdown parser, provides a `header_offset` option, but
5+
Jekyll only allows us to set that globally -- and setting it globally
6+
to two would break our other pages. So, this include lets us take arbitrary
7+
HTML (from rendered markdown) and does some liquid string replacements
8+
to offset its headings. This is pretty janky (even more so because liquid
9+
only allows us to do literal string replacement, not regex replacement),
10+
but I think it *should* work robustly, thanks to the fact that angle
11+
brackets (i.e., `<` and `>`) aren't supposed to appear in HTML unencoded,
12+
and I imagine Kramdown respects that.
13+
{% endcomment %}
14+
{{ include.content
15+
| replace: "<h5", "<h6x"
16+
| replace: "<h4", "<h6x"
17+
| replace: "<h3", "<h5x"
18+
| replace: "<h2", "<h4x"
19+
| replace: "<h1", "<h3x"
20+
| replace: "</h1>", "</h3x>"
21+
| replace: "</h2>", "</h4x>"
22+
| replace: "</h3>", "</h5x>"
23+
| replace: "</h4>", "</h6x>"
24+
| replace: "</h5>", "</h6x>"
25+
| replace: "<h3x", "<h3"
26+
| replace: "<h4x", "<h4"
27+
| replace: "<h5x", "<h5"
28+
| replace: "<h6x", "<h6"
29+
| replace: "</h3x>", "</h3>"
30+
| replace: "</h4x>", "</h4>"
31+
| replace: "</h5x>", "</h5>"
32+
| replace: "</h6x>", "</h6>"
33+
}}

‎_includes/profile_url.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% comment %}
2+
Takes the page object for a JSON:API profile spec and returns its url.
3+
This file can't have whitespace outside this comment block or else the
4+
output will be corrupted.
5+
{% endcomment %}{{ include.page.url | absolute_url | split: "/" | where_exp: "item", "item != 'index'" | join: "/" }}/

‎_includes/site_navigation.html

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<nav class="site-nav">
2+
<div class="nav-inner">
3+
<ul>
4+
{% assign url = page.url|remove:'index.html' %}
5+
{% for link in site.navigation %}
6+
<li {% if url == link.url or url contains "/profiles/" and link.url contains "/extensions" %}class="active"{% endif %}><a href="{{link.url}}" title="{{link.title}}">{{link.title}}</a></li>
7+
{% endfor %}
8+
<li class="version">
9+
<a href="/format/#status" class="pill">v{{ site.latest_version }} <span class="stable">Stable</span></a>
10+
</li>
11+
</ul>
12+
</div>
13+
</nav>

‎_includes/status.md

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,33 +5,37 @@
55

66
{% assign version = include.version %}
77
{% assign is_latest_version_page = include.is_latest_version %}
8-
{% assign is_upcoming_version_page = include.is_upcoming_version %}
8+
{% assign status = include.status %}
99

1010
## <a href="#status" id="status" class="headerlink"></a> Status
1111

1212
{% comment %}
13-
The first paragraph in each case, below, aims to explain what content
14-
the page holds and how that may (or may not) change over time.
13+
The first paragraph in each case below aims to explain what content
14+
the page holds and whether that content is finalized.
1515

1616
Note: all the text below must be outdented and markdownified where it's
1717
included for it to be rendered correctly as markdown.
1818
{% endcomment %}
1919

2020
{% if is_latest_version_page %}
21-
This page represents the latest published version of JSON:API, which is
21+
This page presents the latest published version of JSON:API, which is
2222
currently version {{ site.latest_version }}. New versions of JSON:API **will
2323
always be backwards compatible** using a _never remove, only add_ strategy.
2424
Additions can be proposed in our [discussion forum](http://discuss.jsonapi.org/).
2525

26-
{% elsif is_upcoming_version_page %}
27-
This page represents the **working draft** for the next version of JSON:API,
28-
which is currently expected to be {{ site.latest_version|plus:0.1 }}.
29-
3026
{% elsif version and version > site.latest_version %}
31-
This page will always present the most recent text for JSON:API
32-
v{{ site.latest_version|plus:0.1 }}. Currently, version
33-
{{ site.latest_version|plus:0.1 }} is **still a draft**, so this text is
34-
provisional.
27+
This page will always present the most recent text for JSON:API v{{ site.latest_version|plus:0.1 }}.
28+
Version {{ site.latest_version|plus:0.1 }} is a **{% if status == "rc" %}release
29+
candidate{% else %}working draft{% endif %}**. As such, the content on this
30+
page {% if status != "rc" %}is subject to change.{% else %}is unlikely to
31+
change. However, some changes may still occur if implementation experience
32+
proves that they are necessary before this version is finalized.{% endif %}
33+
34+
{% if include.release_date %}
35+
This version is expected to be finalized and released on **{{ include.release_date | date: "%B %e, %Y" }}**
36+
(provided there are two compliant implementations by that date; if not the
37+
release will wait until such implementations exist to prove its viability).
38+
{% endif %}
3539

3640
{% elsif version and version == site.latest_version %}
3741
This page presents an archived copy of JSON:API version {{ version }}. None
@@ -44,7 +48,6 @@
4448
of the normative text on this page will change. While {{ version }} is no
4549
longer the [latest version](/format/) of JSON:API, **new versions will remain
4650
compatible with this one**, as JSON:API uses a _never remove, only add_ strategy.
47-
4851
{% endif %}
4952

5053
{% comment %}

‎_includes/title_for_version.md

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,10 @@
1313
{% endcomment %}
1414
{% assign version = include.version %}
1515
{% assign is_latest_version_page = include.is_latest_version %}
16-
{% assign is_upcoming_version_page = include.is_upcoming_version %}
1716

1817
{% if is_latest_version_page %}
1918
Latest Specification (v{{ site.latest_version }})
2019

21-
{% elsif is_upcoming_version_page %}
22-
Draft for Next Specification Release
23-
2420
{% elsif version and version > site.latest_version %}
2521
Specification v{{site.latest_version|plus:0.1}} (Still in Development)
2622

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy