Update `/transact` syntax to replace `ledger` with `@graph` + `@id`

[aaj3f]

Description

Similar to fluree/core#19, the syntax of the http-api-gateway /transact endpoint needs to be updated to be standards-compliant rather than use the Fluree proprietary syntax of { ledger: "example/ledger", txn: { ... } }

The JSON-LD compliant way of naming the graph/ledger to which a dataset belongs is to use the top-level keys @id + @graph, such that the @id becomes the identifier/name of the graph/ledger and @graph describes the data existing within that graph/ledger. Thus, the following two examples specify, first, the current syntax used by http-api-gateway and, second, the desired, standards-compliant syntax

{
    "ledger": "example/ledger",
    "txn": {
        "@context": { "schema": "http://schema.org/" },
        "@id": "schema:fluree",
        "@type": "schema:Organization",
        "schema:description": "We ❤️ Data"
    }
}

{
    "@context": { "schema": "http://schema.org/" },
    "@id": "example/ledger",
    "@graph": {
        "@id": "schema:fluree",
        "@type": "schema:Organization",
        "schema:description": "We ❤️ Data"
    }
}

Implementation Details

A few considerations:

• This pattern could ultimately allow multiple transactions against multiple ledgers at once, but this would be a complex item of work and is NOT intended for this ticket (e.g. how would the transactor establish a lock against multiple ledgers for validation/commits). That transaction might look like:

{
    "@context": { ... },
    "@graph": [
        {
            "@id": "ledger/one",
            "@graph": {
                "@id": "ex:andrew",
                "schema:name": "Andrew"
            }
        },
        {
            "@id": "ledger/two",
            "@graph": {
                "@id": "ex:ben",
                "schema:name": "Ben"
            }
        }
    ]
}

• To avoid implicitly allowing multi-ledger transactions, this ticket might include work to require @id and @graph be both (a) top-level-only keys and (b) required keys. Similarly, we might want to throw an error currently if @graph appears as a key in any txn items nested under the top-level @graph
• In terms of the JSON-LD standard, @context could be defined at both/either the top-level (as described above), or it could appear as a lower level context specific to a transaction item against a particular ledger. As we are only supporting transactions against a single graph/ledger, this is less relevant, but we may want to choose to currently only support @context at the top-level and, if so, possibly throw an error if @context appears in a child of @graph.
• It is important to note that, in a valid transaction like the one at the top of this ticket, the value of @graph must support either a single { transaction item } or [{ an }, { array }, { of }, { items }]

[mpoffald]

How is this new top-level "@context" meant to interact with the existing "defaultContext" behavior? Are they the same thing? If not, how are they different?

[mpoffald]

Ok, having thought about this more I think I understand -- the top-level @context is just the same context that would've ordinarily been inside the txn? And therefore has nothing to do with defaultContext.

I just thought it seemed weird to be able supply both defaultContext and @context, and then got confused about what that would mean.