Skip to content
Embabel Worlds

Draft an ODCS contract for a saved view, optionally sampling, saving and binding it

POST
/api/v1/admin/kg/views/{name}/contract
curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/views/example/contract \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "args": { "additionalProperty": "example" }, "bind": true, "persist": true, "sample": true }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

The view’s name, as GET /views lists it.

Query Parameters

Section titled “Query Parameters”
username
string

Optional, and never needed: the call always acts as the signed-in principal. Naming the principal changes nothing; naming anyone else is refused with 403.

Request Body

Section titled “Request Body”

Optional; omitted is a declaration-only preview that reads no data and writes nothing. sample runs the view under a row cap (with args for a parameterized view) to infer types; persist writes the draft into the world; bind also pins the view to it in observe mode and needs persist. Each defaults to false

Media typeapplication/json

How to draft an ODCS contract for a named view, and how far to go with it.

object
args

Arguments for a parameterized view. Used only when sampling.

object
key
additional properties
bind

Also pin the view to the new contract in observe mode. Requires persist.

boolean
persist

Write the draft into the world. False previews it and writes nothing.

boolean
sample

Run the view under a row cap to infer types and suggestions. Off by default: generation reads the declaration only unless asked to touch data.

boolean

Example generated

{
  "args": {
    "additionalProperty": "example"
  },
  "bind": true,
  "persist": true,
  "sample": true
}

Responses

Section titled “Responses”

200

Section titled “200”

The drafted contract and what was done with it

Media typeapplication/json

A drafted ODCS contract for a named view, in draft status and unreviewed.

object
columns
required

One entry per column the view projects, in the order the draft lists them.

Array<object>

One drafted column, and whether its entry was read or inferred.

object
evidence
required

declared (read from the view) or sampled (inferred from rows).

string
logicalType

ODCS logical type, present only when a sample agreed unanimously.

string
name
required

The column’s name, as the view’s RETURN aliases it.

string
suggestions
required

What the sample SUGGESTS but does not prove, as ODCS extension keys.

Array<string>
contractId
required

The contract’s id: a name-based (version 5) UUID over the world and view, so regenerating for the same view yields the same id.

string
disposition
required

What was written and bound, and what an author still has to do.

object
bound
required

Whether the view now pins this contract in observe mode.

boolean
notes
required

Human-readable notes: what was not done, and why.

Array<string>
sampleRows
required

Rows read while sampling. Zero when the view was not run.

integer format: int32
sampleTruncated
required

Whether sampling stopped at its row cap.

boolean
savedAs

World-relative path written, or null when this was a preview.

string
mode
required

declaration or sample — how much of this draft came from data.

string
status
required

ODCS status of the generated document. Always draft.

string
version
required

The contract’s version: 0.1.0 for every generated draft, pre-1.0 because it is unreviewed.

string
view
required

The name of the view the contract was drafted for.

string
yaml
required

The contract document. Review this before promoting anything.

string

Example generated

{
  "columns": [
    {
      "evidence": "example",
      "logicalType": "example",
      "name": "example",
      "suggestions": [
        "example"
      ]
    }
  ],
  "contractId": "example",
  "disposition": {
    "bound": true,
    "notes": [
      "example"
    ],
    "sampleRows": 1,
    "sampleTruncated": true,
    "savedAs": "example"
  },
  "mode": "example",
  "status": "example",
  "version": "example",
  "view": "example",
  "yaml": "example"
}

400

Section titled “400”

The view’s output shape is not contractable, or the draft could not be saved

Media typeapplication/json

A refusal to draft a contract, naming what about the view made it impossible.

object
error
required

Why no contract was drafted: no such view, a projection that cannot be read (*, a bare variable, an unaliased or duplicate column), or a write the world refused.

string

Example generated

{
  "error": "example"
}

401

Section titled “401”

No authenticated principal

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}

403

Section titled “403”

username names someone other than the signed-in principal

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}