blocks family
Read one block's full prop contract — per-variant fields, the block's own heading/body/cta/image mapping, and the props the render reads that the editor cannot express
One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.
curl -X POST https://one.ie/api/ask/blocks:schema \
-H "Authorization: Bearer $ONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data": { "block": "Hero" }}'The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.
Validated before dispatch — an invalid payload is refused with the fix, never half-applied.
block string | string[] required One block name, or up to 10. A retired or family-member name (HeroCentered, Wallet) resolves to its canonical and is reported in `aliasOf` — it is NOT unknown. What comes back from the call.
ok true workspace string | null blocks object[] unknown string[] Names the registry does not know, in the caller's own spelling. ALWAYS PRESENT, empty when every name resolved — a caller must be able to branch on this rather than infer it from a short list. total number Distinct names asked for. returned number Rows in `blocks` — registry and tenant together. truncated object Present ⟺ names were cut. Absent is not false. stale object Every call to blocks:schema, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.
Counting…
Every place in the open source that names blocks:schema, and the file that
answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no
import edge to follow and a grep is the honest shape of the question.
Structure, not volume — the count is in Traffic above.
Called from
Answered by
POST /api/ask/blocks:schema, after the envelope
validates the payload.
blocks family · 2 more
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"block": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "One block name, or up to 10. A retired or family-member name (HeroCentered, Wallet) resolves to its canonical and is reported in `aliasOf` — it is NOT unknown."
}
},
"required": [
"block"
]
} {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"workspace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"blocks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name as asked."
},
"source": {
"type": "string",
"enum": [
"registry",
"tenant"
]
},
"component": {
"type": "string",
"description": "The REGISTERED component this name draws. Differs from `name` only for an alias, and for a tenant block it is the FIRST member."
},
"aliasOf": {
"description": "Present ⟺ `name` is a retired or collapsed member name that the render path rewrites.",
"type": "string"
},
"aliasVariant": {
"type": "string"
},
"label": {
"description": "TENANT ONLY.",
"type": "string"
},
"composedOf": {
"description": "TENANT ONLY — the registry blocks this composition expands into, with the props bound to each. There is no synthetic field table for a tenant block: ask `blocks:schema` for `propsLandOn` to learn what a placement may set.",
"type": "array",
"items": {
"type": "object",
"properties": {
"component": {
"type": "string"
},
"props": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"component",
"props"
]
}
},
"propsLandOn": {
"description": "TENANT ONLY — the member a placement's own props merge onto (always the first). Stored-wins.",
"type": "string"
},
"category": {
"description": "Absent on a tenant block.",
"type": "string"
},
"surface": {
"description": "Absent on a tenant block.",
"type": "string"
},
"description": {
"type": "string"
},
"canonicalVariant": {
"description": "REGISTRY ONLY — the member that renders when no `variant` prop is sent.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"declaredProps": {
"description": "REGISTRY ONLY. Every prop name the collapsed registration accepts. A SUPERSET of what any one variant reads — a prop from the wrong member is accepted and renders nothing, which is why `variants` below is the real answer.",
"type": "array",
"items": {
"type": "string"
}
},
"options": {
"description": "REGISTRY ONLY — legal values for each enum-shaped prop.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {}
}
},
"variants": {
"description": "REGISTRY ONLY — keyed by variant value; the single key '' for a block that is not a collapsed family.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"of": {
"description": "For an array field — the keys each ITEM object takes.",
"type": "array",
"items": {
"type": "string"
}
},
"options": {
"type": "array",
"items": {}
}
}
},
"description": "The props the member that renders THIS variant actually reads. Write to these names."
},
"semantics": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
},
"description": "This block's own role → prop map: heading · body · cta · image. `{}` is honest for a Spacer."
},
"renders": {
"description": "Props the render reads that the editor's fields cannot express — nested array item keys, mostly.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"fields",
"semantics"
]
}
}
},
"required": [
"name",
"source",
"component"
]
}
},
"unknown": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names the registry does not know, in the caller's own spelling. ALWAYS PRESENT, empty when every name resolved — a caller must be able to branch on this rather than infer it from a short list."
},
"total": {
"type": "number",
"description": "Distinct names asked for."
},
"returned": {
"type": "number",
"description": "Rows in `blocks` — registry and tenant together."
},
"truncated": {
"description": "Present ⟺ names were cut. Absent is not false.",
"type": "object",
"properties": {
"rows": {
"type": "number"
},
"limit": {
"type": "number"
},
"reason": {
"type": "string",
"const": "names",
"description": "More than 10 names were asked for; the rest were not read."
}
},
"required": [
"rows",
"limit",
"reason"
]
},
"stale": {
"type": "object",
"properties": {
"declared": {
"type": "number"
},
"actual": {
"type": "number"
}
},
"required": [
"declared",
"actual"
]
}
},
"required": [
"ok",
"workspace",
"blocks",
"unknown",
"total",
"returned"
]
}