Skip to content

fix(registryctl): unify authored nullability on the type union #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeremi wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix(registryctl): unify authored nullability on the type union #630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0433a8a
fix(registryctl): unify structured-output nullability on the type union
jeremi Aug 1, 2026
ce41d6b
fix(registryctl): recover colon-punctuated output paths and un-invert…
jeremi Aug 1, 2026
b629dea
fix(registryctl): declare claim value nullability with the type union
jeremi Aug 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions crates/registryctl/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [Unreleased]

### Changed

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add the required DCO sign-off

The reviewed commit message contains no Signed-off-by: trailer, so it does not satisfy the repository's mandatory DCO policy and will be rejected by any DCO gate; recreate the commit with the author sign-off before merging.

AGENTS.md reference: AGENTS.md:L70-L70

Useful? React with 👍 / 👎.


- BREAKING: a structured output declares nullability the same way at every
type. Object and array outputs use `type: [object, "null"]` and
`type: ["array", "null"]`, which is what scalar outputs already used, and the
separate `nullable:` key they carried is removed. It shipped on composites
only, in 0.16.0, and never applied to scalars, so one grammar had two ways to
say the same thing depending on the type in hand. Migration: delete
`nullable: true` and pair the declared form with `"null"` in the `type` union;
delete `nullable: false` outright, since a form without `"null"` is already
non-nullable. An authored project that still carries the key is rejected by
`registryctl.authoring.yaml.unknown_field` with the offending pointer and the
union syntax to replace it. The `nullable` field on the compiled Registry
Relay and Registry Notary contracts is a different, internal wire surface and
is unchanged.
- BREAKING: a claim value declares nullability with its `type` union, the same
way scalar outputs, structured outputs, and entity fields already do. Write
`type: [string, "null"]` for a nullable claim value and `type: string` for a
required one, and the separate `nullable:` key is removed. It shipped with
the project authoring workflow in 0.10.0 and was the last place on the
authored surface that spelled nullability a second way. Migration: delete
`nullable: true` and pair the declared type with `"null"` in the `type`
union; delete `nullable: false` outright, since a type without `"null"` is
already non-nullable. An authored project that still carries the key is
rejected by `registryctl.authoring.yaml.unknown_field` with the offending
pointer and the union syntax to replace it. The `nullable` field on the
compiled Registry Relay and Registry Notary contracts is a different,
internal wire surface and is unchanged.

## [0.16.0] - 2026-08-01

### Removed
Expand Down
33 changes: 15 additions & 18 deletions crates/registryctl/schemas/project-authoring/documentation-intent.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,10 @@
{ "schema": "project", "pointer": "/$defs/consultations/additionalProperties", "path_kind": "map_value" },
{ "schema": "project", "pointer": "/$defs/consultations/additionalProperties/properties/input/propertyNames", "path_kind": "map_key" },
{ "schema": "project", "pointer": "/$defs/consultations/additionalProperties/properties/input/additionalProperties", "path_kind": "map_value" },
{ "schema": "project", "pointer": "/$defs/claimValueType/oneOf/0", "path_kind": "branch" },
{ "schema": "project", "pointer": "/$defs/claimValueType/oneOf/1", "path_kind": "branch" },
{ "schema": "project", "pointer": "/$defs/claimValueType/oneOf/1/prefixItems/0", "path_kind": "array_item" },
{ "schema": "project", "pointer": "/$defs/claimValueType/oneOf/1/prefixItems/1", "path_kind": "array_item" },
{ "schema": "environment", "pointer": "/properties/integrations/propertyNames", "path_kind": "map_key" },
{ "schema": "environment", "pointer": "/properties/integrations/additionalProperties", "path_kind": "map_value" },
{ "schema": "environment", "pointer": "/properties/entities/propertyNames", "path_kind": "map_key" },
Expand Down Expand Up @@ -180,6 +184,14 @@
{ "schema": "integration", "pointer": "/$defs/scalarType/oneOf/1", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/scalarType/oneOf/1/prefixItems/0", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/scalarType/oneOf/1/prefixItems/1", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/objectType/oneOf/0", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/objectType/oneOf/1", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/objectType/oneOf/1/prefixItems/0", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/objectType/oneOf/1/prefixItems/1", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/arrayType/oneOf/0", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/arrayType/oneOf/1", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/arrayType/oneOf/1/prefixItems/0", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/arrayType/oneOf/1/prefixItems/1", "path_kind": "array_item" },
{ "schema": "integration", "pointer": "/$defs/versions/anyOf/0", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/versions/anyOf/1", "path_kind": "branch" },
{ "schema": "integration", "pointer": "/$defs/versionList/items", "path_kind": "array_item" },
Expand Down Expand Up @@ -885,12 +897,7 @@
{
"schema": "project",
"pointer": "/$defs/claimValue/properties/type",
"purpose": "Declares the boolean, integer, string, or date type of a claim value."
},
{
"schema": "project",
"pointer": "/$defs/claimValue/properties/nullable",
"purpose": "States whether the claim value may be null."
"purpose": "Declares the boolean, integer, string, or date type of a claim value, paired with null when the claim value may be null."
},
{
"schema": "project",
Expand Down Expand Up @@ -1475,12 +1482,7 @@
{
"schema": "integration",
"pointer": "/$defs/outputObject/properties/type",
"purpose": "Selects the closed object form for a structured integration output."
},
{
"schema": "integration",
"pointer": "/$defs/outputObject/properties/nullable",
"purpose": "Declares whether the complete structured output object may be null."
"purpose": "Selects the closed object form for a structured integration output, and declares the object nullable by pairing it with null."
},
{
"schema": "integration",
Expand All @@ -1495,12 +1497,7 @@
{
"schema": "integration",
"pointer": "/$defs/outputArray/properties/type",
"purpose": "Selects the array form for a structured integration output."
},
{
"schema": "integration",
"pointer": "/$defs/outputArray/properties/nullable",
"purpose": "Declares whether the complete structured output array may be null."
"purpose": "Selects the array form for a structured integration output, and declares the array nullable by pairing it with null."
},
{
"schema": "integration",
Expand Down
105 changes: 90 additions & 15 deletions crates/registryctl/schemas/project-authoring/dto-shape-contract.v1.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,34 @@
},
"type": "object"
},
"AuthoredNullType": {
"description": "The `\"null\"` member of an authored composite `type` union.",
"enum": [
"null"
],
"type": "string"
},
"AuthoredNullableType": {
"anyOf": [
{
"$ref": "#/$defs/ClaimValueType"
},
{
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"$ref": "#/$defs/ClaimValueType"
},
{
"$ref": "#/$defs/AuthoredNullType"
}
],
"type": "array"
}
],
"description": "The one authored nullability idiom, shared with `AuthoredSchemaType`.\n\nScalar, object, array, and claim-value declarations all express nullability\nas the JSON-Schema-native `type` union `[<form>, \"null\"]`. The tuple arm\nmakes the two-member form/null order part of the type rather than a runtime\nrule."
},
"ClaimDeclaration": {
"additionalProperties": false,
"properties": {
Expand Down Expand Up @@ -73,19 +101,25 @@
"null"
]
},
"nullable": {
"default": false,
"type": "boolean"
},
"type": {
"$ref": "#/$defs/OutputType"
"$ref": "#/$defs/AuthoredNullableType"
}
},
"required": [
"type"
],
"type": "object"
},
"ClaimValueType": {
"description": "The types a claim value may take. Structured outputs are consulted through\nRelay but are never disclosed as a claim value, so `object`, `array`, and\n`presence` are absent by construction.",
"enum": [
"boolean",
"integer",
"string",
"date"
],
"type": "string"
},
"ConsentDeclaration": {
"enum": [
"not_required",
Expand Down Expand Up @@ -2899,6 +2933,55 @@
],
"type": "object"
},
"AuthoredNullType": {
"description": "The `\"null\"` member of an authored composite `type` union.",
"enum": [
"null"
],
"type": "string"
},
"AuthoredNullableType": {
"anyOf": [
{
"$ref": "#/$defs/AuthoredOutputObjectType"
},
{
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"$ref": "#/$defs/AuthoredOutputObjectType"
},
{
"$ref": "#/$defs/AuthoredNullType"
}
],
"type": "array"
}
],
"description": "The one authored nullability idiom, shared with `AuthoredSchemaType`.\n\nScalar, object, array, and claim-value declarations all express nullability\nas the JSON-Schema-native `type` union `[<form>, \"null\"]`. The tuple arm\nmakes the two-member form/null order part of the type rather than a runtime\nrule."
},
"AuthoredNullableType2": {
"anyOf": [
{
"$ref": "#/$defs/AuthoredOutputArrayType"
},
{
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"$ref": "#/$defs/AuthoredOutputArrayType"
},
{
"$ref": "#/$defs/AuthoredNullType"
}
],
"type": "array"
}
],
"description": "The one authored nullability idiom, shared with `AuthoredSchemaType`.\n\nScalar, object, array, and claim-value declarations all express nullability\nas the JSON-Schema-native `type` union `[<form>, \"null\"]`. The tuple arm\nmakes the two-member form/null order part of the type rather than a runtime\nrule."
},
"AuthoredOutputArrayDeclaration": {
"additionalProperties": false,
"properties": {
Expand All @@ -2916,16 +2999,12 @@
"minimum": 0,
"type": "integer"
},
"nullable": {
"type": "boolean"
},
"type": {
"$ref": "#/$defs/AuthoredOutputArrayType"
"$ref": "#/$defs/AuthoredNullableType2"
}
},
"required": [
"type",
"nullable",
"max_bytes",
"max_items",
"items"
Expand Down Expand Up @@ -2965,16 +3044,12 @@
"minimum": 0,
"type": "integer"
},
"nullable": {
"type": "boolean"
},
"type": {
"$ref": "#/$defs/AuthoredOutputObjectType"
"$ref": "#/$defs/AuthoredNullableType"
}
},
"required": [
"type",
"nullable",
"max_bytes",
"fields"
],
Expand Down
44 changes: 36 additions & 8 deletions crates/registryctl/schemas/project-authoring/integration.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,12 +68,10 @@
"active": { "type": "boolean" },
"parents": {
"type": "array",
"nullable": false,
"max_bytes": 4096,
"max_items": 2,
"items": {
"type": "object",
"nullable": false,
"max_bytes": 2048,
"fields": {
"name": {
Expand Down Expand Up @@ -577,14 +575,45 @@
"schema": {"x-registry-field": "property", "$ref": "#/$defs/outputSchema" }
}
},
"objectType": {
"description": "The object form, optionally paired with null for a nullable structured output object.",
"oneOf": [
{"x-registry-field": "branch", "const": "object" },
{
"x-registry-field": "branch",
"type": "array",
"prefixItems": [
{"x-registry-field": "array_item", "const": "object" },
{"x-registry-field": "array_item", "const": "null" }
],
"minItems": 2,
"maxItems": 2
}
]
},
"arrayType": {
"description": "The array form, optionally paired with null for a nullable structured output array.",
"oneOf": [
{"x-registry-field": "branch", "const": "array" },
{
"x-registry-field": "branch",
"type": "array",
"prefixItems": [
{"x-registry-field": "array_item", "const": "array" },
{"x-registry-field": "array_item", "const": "null" }
],
"minItems": 2,
"maxItems": 2
}
]
},
"outputObject": {
"description": "A recursively typed object output with a canonical byte ceiling and an always-closed field map.",
"type": "object",
"additionalProperties": false,
"required": ["type", "nullable", "max_bytes", "fields"],
"required": ["type", "max_bytes", "fields"],
"properties": {
"type": {"x-registry-field": "property", "const": "object" },
"nullable": {"x-registry-field": "property", "type": "boolean" },
"type": {"x-registry-field": "property", "$ref": "#/$defs/objectType" },
"max_bytes": {"x-registry-field": "property", "type": "integer", "minimum": 1, "maximum": 65536 },
"fields": {
"x-registry-field": "property",
Expand All @@ -600,10 +629,9 @@
"description": "A recursively typed array output with canonical byte and item-count ceilings.",
"type": "object",
"additionalProperties": false,
"required": ["type", "nullable", "max_bytes", "max_items", "items"],
"required": ["type", "max_bytes", "max_items", "items"],
"properties": {
"type": {"x-registry-field": "property", "const": "array" },
"nullable": {"x-registry-field": "property", "type": "boolean" },
"type": {"x-registry-field": "property", "$ref": "#/$defs/arrayType" },
"max_bytes": {"x-registry-field": "property", "type": "integer", "minimum": 1, "maximum": 65536 },
"max_items": {"x-registry-field": "property", "type": "integer", "minimum": 1, "maximum": 256 },
"items": {"x-registry-field": "property", "$ref": "#/$defs/outputSchema" }
Expand Down
19 changes: 18 additions & 1 deletion crates/registryctl/schemas/project-authoring/project.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -536,7 +536,24 @@
"claimValue": {
"description": "Explicit claim value type, nullability, and encoded-size bound for a claim derived from declared Relay consultation outputs.",
"type": "object", "additionalProperties": false, "required": ["type"],
"properties": { "type": {"x-registry-field": "property", "enum": ["boolean", "integer", "string", "date"] }, "nullable": {"x-registry-field": "property", "type": "boolean" }, "max_bytes": {"x-registry-field": "property", "type": "integer", "minimum": 1, "maximum": 65536 } }
"properties": { "type": {"x-registry-field": "property", "$ref": "#/$defs/claimValueType" }, "max_bytes": {"x-registry-field": "property", "type": "integer", "minimum": 1, "maximum": 65536 } }
},
"claimValueType": {
"description": "Supported claim value type, optionally paired with null for a nullable claim value.",
"oneOf": [
{"x-registry-field": "branch", "enum": ["boolean", "integer", "string", "date"] },
{
"x-registry-field": "branch",
"type": "array",
"prefixItems": [
{"x-registry-field": "array_item", "enum": ["boolean", "integer", "string", "date"] },
{"x-registry-field": "array_item", "const": "null" }
],
"minItems": 2,
"maxItems": 2,
"uniqueItems": true
}
]
}
}
}
Loading
Loading