Preserving item order where needed

[datadavev]

Unlike plain JSON, lists in JSON-LD are unordered [1, 2]. In cases where ordering of items is to be preserved, it is necessary to use the @list keyword to specify the type of container for the items.

Ordering may be important in consumer tool chains, for example a list of authors or creators should be ordered as intended when rendering a view of the metadata.

Example 1. Order will be preserved for this list of creators:

{
  "@context": {
    "@vocab": "https://schema.org/"
  },
  "@id": "order_01",
  "@type": "Dataset",
  "creator": {
    "@list": [
      {
        "@id": "https://www.sample-data-repository.org/person/51317",
        "@type": "Person",
        "name": "Dr Uta Passow"
      },
      {
        "@id": "https://www.sample-data-repository.org/person/50663",
        "@type": "Person",
        "name": "Dr Mark Brzezinski"
      }
    ]
  }
}

Example 2. Ordering for this list of creators will not be preserved:

{
  "@context": {
    "@vocab": "https://schema.org/"
  },
  "@id": "unordered_01",
  "@type": "Dataset",
  "creator": [
    {
      "@id": "https://www.sample-data-repository.org/person/51317",
      "@type": "Person",
      "name": "Dr Uta Passow"
    },
    {
      "@id": "https://www.sample-data-repository.org/person/50663",
      "@type": "Person",
      "name": "Dr Mark Brzezinski"
    }
  ]
}

Ordering may be specified globally within the document by specifying the container type in a context. For example:

Example 3. Ordering of a list of creators is preserved anywhere such a list appears within the context.

{
  "@context": {
    "@vocab": "https://schema.org/",
    "creator": {
      "@container": "@list"
    }
  },
  "@id": "order_02",
  "@type": "Dataset",
  "creator": [
    {
      "@id": "https://www.sample-data-repository.org/person/51317",
      "@type": "Person",
      "name": "Dr Uta Passow"
    },
    {
      "@id": "https://www.sample-data-repository.org/person/50663",
      "@type": "Person",
      "name": "Dr Mark Brzezinski"
    }
  ]
}

1. json-ld/json-ld.org#12 2. https://www.w3.org/TR/json-ld/#lists

[ashepherd]

great catch, @datadavev

[datadavev]

For reference, here's a gist that demonstrates extracting ordered vs. unordered creator names using SPARQL.

[datadavev]

My impression is that this is a fundamental issue that should be resolved with at least some guidance in the 1.3 release.

schema.org seems to recognize the challenge of ordered lists through the itemList structure. Some examples using this approach applied to elements of Dataset plus a more general recommendation to apply @list where appropriate may be all that is required for closing this issue.

[mbjones]

I agree. I think updating all of our examples to use @list appropriately would help make it clear, and we should have a brief explanation of the issue in the guide so that people understand the implications of @list and its utility.

[ashepherd]

+1 for v1.3

[mbjones]

I started a draft of this in a new branch feature_135_jsonld_keywords. You can read the section here:

https://github.com/ESIPFed/science-on-schema.org/blob/feature_135_jsonld_keywords/guides/GETTING-STARTED.md#json-ld

Feel free to edit directly on the branch. I will start a PR to track feedback as well.

[jaygray0919]

@mbjones Nice intro. One point that may be of interest here. Google SDTT validates vocabulary and grammar (V/G). Short-hand: "validates meaning". JSON-LD Playground only validates syntax. It is possible to express jibberish on JSON-LD Playground. [i.e: multiple @context statements initialize terms only; not relationships] (note: am not criticizing Playground - it does what the JSON validator does while adding the Linked Data features of JSON-LD and is very useful)

In contrast, Gregg Kellogg's Structured Data Linter (SDL), like GSDTT, validates V/G (meaning). The current V/G validation baseline is schema.org.

We are testing integration of other OWL-based ontologies with SDL so that we can validate schema+alt-V/G. Our test cases are PlantOntology and UN FAO Agrontology. When we get that working, it opens the opportunity to validate V/G using complementary ontologies (domain-specific "extensions" to schema).

In effect, we use schema as a baseline (for @Types that are general-purpose) and add domain axioms. Still early days here, but may be interesting to your work as it takes shape.

[jaygray0919]

Addendum. Some of the above points are discussed here: https://github.com/schemaorg/schemaorg/issues/2790#issuecomment-840745775

[mbjones]

NB: The PR I startted describes the issue but we still have a TODO to update all of our example documents to use the @list keyword where appropriate.

[mbjones]

PR #135 was merged and is a good start. But we still need to updated example documents and provide an overview of using @list in the "Roles of People" section of Dataset.md

• [ ] Update minimal and full example docs and guide examples with @list
• [ ] Describe use of @list in Dataset.md in "Roles of People"