Skip to content

Spec store

The spec store is a library of ready-made specifications for blocks, vDAGs, clusters, components and more. Save a spec once, share it, search for it, and deploy it directly through the Parser, or use it as a starting point and customize it.

At a glance

Runs on: the management cluster, as spec-registry-svc (NodePort 30107).
Deploy a saved spec: POST /api/with-spec/<action>?specUri=<uri> on the Parser.

Schema

@dataclass
class SpecStoreObject:
    specUri: str = ''   # specName:specVersion.version-specVersion.tag
    specType: str = ''
    specName: str = ''
    specVersion: Dict[str, str] = field(default_factory=lambda: {"version": "", "tag": ""})
    specDescription: str = ''
    specMetadata: Dict[str, Any] = field(default_factory=dict)
    specTags: List[str] = field(default_factory=list)
    specData: str = ''
Field Type Description
specUri str Unique ID, generated as {specName}:{version}-{tag}, for example MySpec:1.0-stable.
specType str What kind of spec this is (see Spec types).
specName str Name of the spec.
specVersion dict version (for example 1.0) and tag (for example stable or beta).
specDescription str What the spec is for.
specMetadata dict Extra details: author, creation date, dependencies and so on.
specTags list Tags, for search.
specData str The specification itself, as a string (usually JSON).

Spec types

specType Contains
block A block spec
vdag A vDAG spec
cluster A cluster spec
component A component spec
search A similarity search spec
mgmtCommand A management command

APIs

Endpoint Method What it does
/spec POST Save a spec.
/spec/<specUri> GET Get a spec.
/spec/<specUri> PUT Update any field except specUri.
/spec/<specUri> DELETE Delete a spec.
/specs POST Search specs with a MongoDB-style filter.
# Save
curl -X POST http://<server-url>/spec \
     -H "Content-Type: application/json" \
     -d '{
          "specName": "MySpec",
          "specType": "API",
          "specVersion": {"version": "1.0", "tag": "stable"},
          "specDescription": "This is an API specification.",
          "specMetadata": {"author": "John Doe"},
          "specTags": ["v1", "stable"],
          "specData": "{\"endpoints\": [{\"path\": \"/users\", \"method\": \"GET\"}]}"
      }'

# Get
curl -X GET http://<server-url>/spec/MySpec:1.0-stable

# Update
curl -X PUT http://<server-url>/spec/MySpec:1.0-stable \
     -H "Content-Type: application/json" \
     -d '{
          "specDescription": "Updated description for the API.",
          "specMetadata": {"author": "Jane Doe"},
          "specTags": ["v1", "stable", "updated"]
      }'

# Delete
curl -X DELETE http://<server-url>/spec/MySpec:1.0-stable

# Search
curl -X POST http://<server-url>/specs \
     -H "Content-Type: application/json" \
     -d '{
          "specType": "API",
          "specVersion.version": {"$gte": "1.0"},
          "specTags": {"$in": ["stable"]}
      }'