It is strange that ORE defines ore:lineage as a very specific kind of provenance of an aggregation.

While I think it is important that we specify the meaning of provenance of proxies - such as its creator means who added the resource to the aggregation - I think ore:lineage should be hidden a bit more as it is just one particular form of provenance:

ore:lineage is, thus, a relationship between two Proxy objects, both of which MUST have the same Resource for which they are proxies. The meaning is that the Resource for which the subject of the relationship is a Proxy was discovered in the Aggregation in which the object Proxy's resource is aggregated.

There are many other reasons behind a proxy being related to a different proxy, for instance membership of a more generic aggregation (managers of a company) is implied by membership in a specific aggregation (executive managers) - expressed using prov:specializationOf or prov:wasDerivedFrom

{ "@id": "http://example.com/executives/member3",
  "@type": "Proxy",
  "proxyIn": "http://example.com/executives/",
  "prov:specializationOf" {
    "@id": "http://example.com/managers/member5",
    "proxyIn": "http://example.com/managers/"
  }
}

Or a membership was attributed to someone adding them to the collection:

{ "@id": "http://example.com/executives/member3",
  "@type": "Proxy",
  "proxyIn": "http://example.com/executives/",
  "prov:wasAttributedTo" {
      "foaf:name": "Stian"
   }
}

(Here you might want to use pav:createdBy to indicate the secretary who technically created the ORE membership, and pav:authoredBy to the director who authorized the new executive member. - but let's not get carried away!)

What I am trying to say is that ore:lineage is defined very specifically to "was discovered in another aggregation", and there are many other forms of provenance of a proxy (e.g. of a membership of an aggregation), and therefore we should downplay it, perhaps both here and in the ORE Vocabulary.

The References section needs to be updated as it was copied from the ORE RDF/XML document. Some of the references have since got newer versions.

Although I like having the [RDF] style notations in the text - I have tried to change those to include the direct link rather than an anchor link to the References list as I find those very annoying and confusing.

I've started adding links to the related ORE Vocabulary entry, e.g. proxies section links to the anchor for Proxy in ORE Vocabulary.

This task is to ensure that each sub-section has such links to the ORE Vocabulary where a term is introduced. There should not be such links all over the place, e.g. don't change every Aggregation to be a hyperlink!

Note: Some headers might not have id yet.

I and Matt tried to put together a simple JSON-LD Frame:

http://stain.github.io/ore/frame.jsonld

which in theory could be used to force an ORE JSON-LD document to fit within a pre-determined JSON structure - and hence be easier to process by a web client etc. without understanding RDF.

The frame, and the section's text, still need some work. To test the frame, use the Flattened Form of the "Complete example":

{
  "@graph": [
    {
      "@id": "http://example.com/aggregation-1",
      "@type": "http://www.openarchives.org/ore/terms/Aggregation",
      "http://www.openarchives.org/ore/terms/aggregates": [
        {
          "@id": "http://example.com/document-1"
        },
        {
          "@id": "http://other.example.org/data-2"
        },
        {
          "@id": "http://other.example.org/aggregation-3"
        },
        {
          "@id": "urn:uuid:09561248-bf55-4c85-930a-9a7a60e81602"
        }
      ],
      "http://www.openarchives.org/ore/terms/isDescribedBy": [
        {
          "@id": "http://example.com/aggregation-1.rdf"
        },
        {
          "@id": "http://example.com/aggregation-1.jsonld"
        }
      ],
      "http://www.openarchives.org/ore/terms/similarTo": {
        "@id": "http://dx.doi.org/10.1002/cpe.1594"
      }
    },
    {
      "@id": "./",
      "@type": "http://www.openarchives.org/ore/terms/ResourceMap",
      "http://www.openarchives.org/ore/terms/describes": {
        "@id": "http://example.com/aggregation-1"
      }
    },
    {
      "@id": "http://other.example.org/aggregation-2",
      "@type": "http://www.openarchives.org/ore/terms/Aggregation",
      "http://www.openarchives.org/ore/terms/isDescribedBy": {
        "@id": "http://other.example.org/aggregation-2.rdf"
      }
    },
    {
      "@id": "http://other.example.org/aggregation-3",
      "@type": "http://www.openarchives.org/ore/terms/Aggregation",
      "http://www.openarchives.org/ore/terms/isDescribedBy": [
        {
          "@id": "http://other.example.org/aggregation-3.rdf"
        },
        {
          "@id": "http://other.example.org/aggregation-3.jsonld"
        }
      ]
    },
    {
      "@id": "http://other.example.org/data-2",
      "http://www.openarchives.org/ore/terms/isAggregatedBy": {
        "@id": "http://other.example.org/aggregation-2"
      }
    },
    {
      "@id": "urn:uuid:05bd5e0c-94c7-4856-a53f-7f6cf0756751",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/lineage": {
        "@id": "urn:uuid:360ea070-efee-11e3-ac10-0800200c9a66"
      },
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "http://other.example.org/data-2"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://example.com/aggregation-1"
      }
    },
    {
      "@id": "urn:uuid:09561248-bf55-4c85-930a-9a7a60e81602",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "http://example.com/document-1"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://other.example.org/aggregation-3"
      }
    },
    {
      "@id": "urn:uuid:318745e0-5ea4-4a68-8a0a-ab27ab96985a",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "urn:uuid:09561248-bf55-4c85-930a-9a7a60e81602"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://example.com/aggregation-1"
      }
    },
    {
      "@id": "urn:uuid:360ea070-efee-11e3-ac10-0800200c9a66",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "http://other.example.org/data-2"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://other.example.org/aggregation-2"
      }
    },
    {
      "@id": "urn:uuid:c0f5f1ad-5269-4cfc-b9f5-e9621c499f53",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "http://other.example.org/aggregation-3"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://example.com/aggregation-1"
      }
    },
    {
      "@id": "urn:uuid:d4e63599-d28d-4966-8606-dbb985a865f2",
      "@type": "http://www.openarchives.org/ore/terms/Proxy",
      "http://www.openarchives.org/ore/terms/proxyFor": {
        "@id": "http://example.com/document-1"
      },
      "http://www.openarchives.org/ore/terms/proxyIn": {
        "@id": "http://example.com/aggregation-1"
      }
    }
  ]
}

ORE predates PROV-O, which now has the concept of prov:alternateOf - which sounds like a better term than 'similarTo'.

Should we rather recommend prov:alternateOf?

Perhaps the ORE Vocabulary should be updated to use prov:alternateOf as superproperty?

JSON-LD style is often light-weight, relying on properties and domain/ranges, and don't usually pepper @type on objects which type is already given by their properties.

However, @type makes it easier to execute SPARQL queries without having to do OWL reasoning or reflecting the whole object structure in SPARQL.

So should we keep this part of section 2?

The @type SHOULD be provided for ORE resources of type Aggregation, ResourceMap, Proxy, and MAY be provided for resources of type AggregatedResource and others.

An alternative context is available at https://w3id.org/ore/context-ore, which defines ORE terms with the ore: prefix. This context MAY be used instead, for instance to avoid naming conflicts when including the ORE context in another JSON-LD context.

Should this be included? The reason I made it was thinking of the case of other people importing the ORE context within an application-specific context. We might not want to hijack non-prefixed names like "describes".

If it is to be included, does the text need more explanation on to when it should and should not be used?

This URI currently redirects to http://stain.github.io/ore/context.json, which contains the JSON-LD context to be used. While this is perfectly ok in general, when using services like the JSON-LD playground (http://json-ld.org/playground/), which is very useful to test the generated JSON-LD, the context cannot be dereferenced correctly.

It may be that CORS is not supported, although there may be another reason as well for this misbehaviour.

If the top-level ResourceMap does not specify @id, it comes out as an anonymous node rather than referring to "the document itself".

At first glance it would seem best to recommend to add

"@id": ""

in order to identify the resource map as the retrieved resource.

However, one could imagine a poor mans ORE set up, where requesting the Aggregation itself somehow directly responds with the ResourceMap instead of doing a HTTP redirect to the ResourceMap resource:

GET http://example.com/aggregation-1 HTTP/1.1
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json
Vary: Accept

{ "@context": "https://w3id.org/ore/context",
  "@type": "ResourceMap",
  "describes": { "@type": "Aggregation"  
                         "@id": "http://example.com/aggregation-1"
                       }
}

This response is "kind of" OK by Linked Data standards, the Resource Map is not identified (bnode), but we know it exists. When parsing this, to ensure you are picking the 'right' aggregation in the resource map, the client would just have to look for:

SELECT ?aggr WHERE { 
    ?resourceMap ore:describes ?aggr .
}

... and in this case we should NOT RECOMMEND to use describes anywhere but the top-level.

However ORE data model has a bit stricter definition for Resource Map:

Each Resource Map MUST be identified by a single protocol-based URI, which MUST be distinct from the Aggregation identified by the Resource Map. This specification uses URI-R to denote URIs that identify Resource Maps. There MAY be multiple Resource Maps for a single Aggregation. Each Resource Map MUST have a distinct URI (rather than forming multiple Representations from a single URI-R). A deference of a URI-R results in a serialization which the assertions described above can be extracted as a set of triples that when combined form an RDF Graph that MUST conform to a well-defined structure.

So I guess the ORE JSON-LD specification should reflect this.

This can be achived by either hard-coding "@id":

{ "@id": "http://example.com/aggregation-1.jsonld"
   "describes" { "@id": "http://example.com/aggregation-1" } 
}

By using the empty @id and Content-Location:

GET http://example.com/aggregation-1 HTTP/1.1
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json
Content-Location: http://example.com/aggregation-1.jsonld
Vary: Accept

{ "@context": "https://w3id.org/ore/context",
  "@id": "",
  "@type": "ResourceMap",
  "describes": { "@type": "Aggregation"  
                         "@id": "http://example.com/aggregation-1"
                       }
}

The second case is in many ways 'more correct' - but also easier to get wrong..

The 'best' solution is to do a classic HTTP 303 See Other to a representation-specific Resource Map:

GET http://example.com/aggregation-1 HTTP/1.1
Accept: application/ld+json

HTTP/1.1 303 See Other
Location: http://example.com/aggregation-1.jsonld
Vary: Accept


GET http://example.com/aggregation-1.jsonld HTTP/1.1
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json

{ "@context": "https://w3id.org/ore/context",
  "@id": "",
  "@type": "ResourceMap",
  "describes": { "@type": "Aggregation"  
                         "@id": "http://example.com/aggregation-1"
                       }
}

A simpler best-practice could be to identify the Aggregation with a hash-based URI:

{ "@id": "http://example.com/aggregation-1"
   "describes" { "@id": "http://example.com/aggregation-1#" } 
}

but this would not as easily allow for multiple resource map representations.