pull: Add JSON-LD markup
authorW. Trevor King <wking@tremily.us>
Thu, 4 Jan 2018 23:44:17 +0000 (15:44 -0800)
committerW. Trevor King <wking@tremily.us>
Mon, 26 Mar 2018 16:39:37 +0000 (09:39 -0700)
commit8398a3573162bb584506a1ce0fa0c88f9db4fd91
treeeea4ca50a26eada958fa928a60c278e417e60cfc
parentee338b3624a260d90509e4b0dac53f926b1e29e6
pull: Add JSON-LD markup

This should help with forward/backward compatibility, because
consumers can use JSON-LD to extract the semantic meaning regardless
of how I lay out the data.  From [1]:

  This information allows developers to re-use each other's data
  without having to agree to how their data will interoperate on a
  site-by-site basis.

There's a framing spec in the works [2] to support "request your own
layout" in an API.

I had to cludge a bit to support FSF IDs in licenses-full.json.  The
released JSON-LD 1.0 has index maps, but [3]:

  Note how the index keys do not appear in the Linked Data below, but
  would continue to exist if the document were compacted or
  expanded...

which isn't very useful for folks who are parsing the file as JSON-LD
and who need access to the FSF IDs.  To work around that, I've used
the FSF IDs as both the 'licenses' keys and as 'id' entries in the
'licenses' values.

We might be able to specify the semantics of the object keys with the
unreleased 1.1 [4] and its ID maps [5], but I've left that off for
now.

There is some background on classifying non-URI identifiers in [6].
Currently I'm not classifying my identifiers.

I'm using HTTPS identifiers for schema.org, because that's the
long term target [7].

I've tested the output JSON-LD in [8], and the compacted
licenses-full.json looks like:

  {
    "http://tremily.us/fsf/schema/license.jsonld": [
      {
        "@index": "ACDL",
        "https://schema.org/identifier": "ACDL",
        "https://schema.org/keywords": "libre",
        "https://schema.org/name": "Apple's Common Documentation License, Version 1.0",
        "https://schema.org/url": {
          "@list": [
            "https://www.gnu.org/licenses/license-list.html#ACDL",
            "http://fedoraproject.org/wiki/Licensing/Common_Documentation_License"
          ]
        }
      },
      {
        "@index": "AGPLv1.0",
        "https://schema.org/identifier": [
          "AGPLv1.0",
          {
            "@index": "spdx",
            "@value": "AGPL-1.0"
          }
        ],
        "https://schema.org/keywords": "libre",
        "https://schema.org/name": "Affero General Public License version 1",
        "https://schema.org/url": {
          "@list": [
            "https://www.gnu.org/licenses/license-list.html#AGPLv1.0",
            "http://directory.fsf.org/wiki/License:AGPLv1"
          ]
        }
      },
      ...
    ]
  }

[1]: https://www.w3.org/TR/2014/REC-json-ld-20140116/#h3_the-context
[2]: https://json-ld.org/spec/latest/json-ld-framing/
[3]: https://www.w3.org/TR/2014/REC-json-ld-20140116/#data-indexing
[4]: https://json-ld.org/spec/latest/json-ld/#changes-since-1-0-recommendation-of-16-january-2014
[5]: https://json-ld.org/spec/latest/json-ld/#node-identifier-indexing
[6]: http://meta.schema.org/docs/datamodel.html#identifierBg
[7]: http://schema.org/docs/faq.html#19
[8]: https://json-ld.org/playground/
pull.py