w3c / w3c/json-ld-syntax

clarify that `@none @id` are blank nodes, swap Examples 104 and 105

Open
#397 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Editorial ErratumRaised
Dominant language
HTML
Stars
139
Forks
23
PR merge metrics
No merged PRs in 30d

Description

I suggest the following editorial changes:

  • Edit Example 105
    • The special index @none is used for indexing node objects which do not have an @id, which is useful to maintain a normalized representation.

    • The special index @none is used for indexing node objects which do not have an @id, i.e. are blank nodes. This is useful to maintain a normalized representation. In cases where multiple blank nodes may be present, it is useful to combine @id with @set, see the next example

  • Swap Examples 104 and 105
  • Edit the old Example 104:
    • When compacting, this ensures that a JSON-LD processor will use the array form for all values of node identifiers.

    • When compacting, this ensures that a JSON-LD processor will use the array form for all values of node identifiers. This ensures a normalized representation in case of blank nodes, all of which will be mapped to @none and therefore need an array to hold their values.

    • Edit its code to the following (last 2 blocks changed):
{
  "@context": {
    "@version": 1.1,
    "schema": "http://schema.org/",
    "name": "schema:name",
    "body": "schema:articleBody",
    "words": "schema:wordCount",
    "post": {
      "@id": "schema:blogPost",
      "@container": ["@id", "@set"]
    }
  },
  "@id": "http://example.com/",
  "@type": "schema:Blog",
  "name": "World Financial News",
  "post": {
    "http://example.com/posts/1/en": [{
      "body": "World commodities were up today with heavy trading of crude oil...",
      "words": 1539
    }],
    "http://example.com/posts/1/de": [{
      "body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
      "words": 1204
    }],
    "@none": [{
        "body": "First object without an @id",
         "words": 201
      }, 
      {
        "body": "Second object without an @id",
        "words": 202
    }]
  }
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Examples 104 and 105 in the linked JSON-LD Syntax specification. Apply the requested ordering, explanatory text, and example JSON changes, then verify that the examples render correctly and clearly describe blank-node indexing with @none and @set.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.