Skip to content

Introduce deprecated annotations #6

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

Merged
raginpirate merged 4 commits into from
Feb 20, 2026
+520 −43
Merged

Introduce deprecated annotations #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3d25615
introduce schema-transition annotations
raginpirate Feb 16, 2026
a59e04a
linter fixes
raginpirate Feb 16, 2026
5170d8f
add description validation to the linter as well; fix dup description…
raginpirate Feb 20, 2026
f3e3f3d
comment nit
raginpirate Feb 20, 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
62 changes: 56 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,12 +258,13 @@ Annotations are stripped; output is standard JSON Schema.

**Resolution rules:**

| Value | Effect on Properties | Effect on Required Array |
| --------------- | -------------------- | ------------------------ |
| `"omit"` | Field removed | Field removed |
| `"required"` | Field kept | Field added |
| `"optional"` | Field kept | Field removed |
| (no annotation) | Field kept | Unchanged |
| Value | Effect on Properties | Effect on Required Array |
| ----------------------------------------------------------------------- | -------------------- | ------------------------ |
| `"omit"` | Field removed | Field removed |
| `"required"` | Field kept | Field added |
| `"optional"` | Field kept | Field removed |
| (no annotation) | Field kept | Unchanged |
| `{ "transition": { "from", "to", "description" } }` (schema transition) | Matches `from` value | Matches `from` value |

Annotations can be **shorthand** (all operations) or **per-operation**, and request/response are independent:

Expand All @@ -283,6 +284,55 @@ Annotations can be **shorthand** (all operations) or **per-operation**, and requ

Valid operations: `create`, `read`, `update`, `complete`.

#### Schema transitions

Use a **schema-transition object** to signal a field contract will change, with a human-readable reason:

```json
{
"transition": {
"from": "required",
"to": "omit",
"description": "Legacy id will be removed in v2; use resource_id instead."
}
}
```

- **`from`** and **`to`** must be one of: `"omit"`, `"optional"`, `"required"`, and must be **distinct** (same value for both is invalid).
- **`description`** is required and should explain the change and what to do instead.

During the transition period the resolved schema **uses the `from` value** as the field's visibility, so previous implementers are not immediately affected. The resolver emits the schema-transition context into the output schema:

- **`x-ucp-schema-transition`**: `{ "from", "to", "description" }` on the property for tooling and docs.
- **`deprecated`: true** on the property only when the field is being **removed** (`to` is `"omit"`).

**Example: Removing a required field**

```json
// Phase 1: Field is required
{ "ucp_request": { "update": "required" } }

// Phase 2: Schema transition (field stays required in resolved schema; tooling offers warnings)
{ "ucp_request": { "update": { "transition": { "from": "required", "to": "omit", "description": "Will be removed in v2." } } } }

// Phase 3: Remove
{ "ucp_request": { "update": "omit" } }
```

**Shorthand schema transition** (same transition for all operations):

```json
{
"ucp_request": {
"transition": {
"from": "required",
"to": "omit",
"description": "Removed in v2."
}
}
}
```

### Schema Composition

UCP payloads are self-describing — they embed `ucp.capabilities` metadata declaring which schemas apply. This lets multiple capability schemas compose into one:
Expand Down
3 changes: 3 additions & 0 deletions src/error.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,9 @@ pub enum ResolveError {
#[error("unknown visibility \"{value}\" at {path}: expected omit, required, or optional")]
UnknownVisibility { path: String, value: String },

#[error("invalid schema transition at {path}: {message}")]
InvalidSchemaTransition { path: String, message: String },

#[error("invalid schema: {message}")]
InvalidSchema { message: String },

Expand Down
210 changes: 192 additions & 18 deletions src/linter.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ use serde::Serialize;
use serde_json::Value;

use crate::loader::{load_schema, navigate_fragment};
use crate::types::{json_type_name, Visibility, UCP_ANNOTATIONS, VALID_OPERATIONS};
use crate::types::{
is_valid_schema_transition, json_type_name, Visibility, UCP_ANNOTATIONS, VALID_OPERATIONS,
};

/// Severity level for diagnostics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
Expand Down Expand Up @@ -332,6 +334,12 @@ fn check_annotation_value(
for (op, val) in map {
let op_path = format!("{}/{}", annotation_path, op);

// Handle shorthand transition key
if op == "transition" {
check_transition_object(val, key, file, &op_path, diagnostics);
continue;
}

// Warn on unknown operations
if !VALID_OPERATIONS.contains(&op.as_str()) {
diagnostics.push(Diagnostic {
Expand All @@ -348,31 +356,52 @@ fn check_annotation_value(
}

// Check value is valid
if let Value::String(s) = val {
if Visibility::parse(s).is_none() {
match val {
Value::String(s) => {
if Visibility::parse(s).is_none() {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E004".to_string(),
file: file.to_path_buf(),
path: op_path,
message: format!(
"invalid {} value \"{}\": expected omit, required, or optional",
key, s
),
});
}
}
Value::Object(obj) => {
// Per-operation transition: { "update": { "transition": { ... } } }
if let Some(t) = obj.get("transition") {
check_transition_object(t, key, file, &op_path, diagnostics);
} else {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E005".to_string(),
file: file.to_path_buf(),
path: op_path,
message: format!(
"invalid {} value type: expected string or transition object, got {}",
key,
json_type_name(val)
),
});
}
}
_ => {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E004".to_string(),
code: "E005".to_string(),
Copy link

@drewolson-google drewolson-google Feb 20, 2026

Choose a reason for hiding this comment

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

Is this intentional? Did something become slightly more-or-less severe?

Copy link
Contributor Author

@raginpirate raginpirate Feb 20, 2026

Choose a reason for hiding this comment

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

I think you're just seeing the artifact of the code-shuffle here Drew!

"invalid {} value "{}": expected omit, required, or optional" is staying as E004.

E005 can occur in two different ways now: either the top-level obj is failing to be a string or transition obj, or the sub-obj failed to be it.

file: file.to_path_buf(),
path: op_path,
message: format!(
"invalid {} value \"{}\": expected omit, required, or optional",
key, s
"invalid {} value type: expected string or transition object, got {}",
key,
json_type_name(val)
),
});
}
} else {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E005".to_string(),
file: file.to_path_buf(),
path: op_path,
message: format!(
"invalid {} value type: expected string, got {}",
key,
json_type_name(val)
),
});
}
}
}
Expand All @@ -392,6 +421,63 @@ fn check_annotation_value(
}
}

/// Validate a schema transition object { "from", "to", "description" }.
fn check_transition_object(
value: &Value,
key: &str,
file: &Path,
path: &str,
diagnostics: &mut Vec<Diagnostic>,
) {
let Some(obj) = value.as_object() else {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E005".to_string(),
file: file.to_path_buf(),
path: path.to_string(),
message: format!(
"invalid {} transition: expected object, got {}",
key,
json_type_name(value)
),
});
return;
};

let from = obj.get("from").and_then(|v| v.as_str()).unwrap_or("");
let to = obj.get("to").and_then(|v| v.as_str()).unwrap_or("");
let description = obj
.get("description")
.and_then(|v| v.as_str())
.unwrap_or("");

if description.is_empty() {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E004".to_string(),
file: file.to_path_buf(),
path: path.to_string(),
message: format!(
"invalid {} transition: missing required field \"description\"",
key
),
});
}

if !is_valid_schema_transition(from, to) {
diagnostics.push(Diagnostic {
severity: Severity::Error,
code: "E004".to_string(),
file: file.to_path_buf(),
path: path.to_string(),
message: format!(
"invalid {} schema transition: \"from\" ({}) and \"to\" ({}) must be distinct visibility values (omit, required, optional)",
key, from, to
),
});
}
}

/// Collect all .json files in a path (file or directory).
fn collect_schema_files(path: &Path) -> Vec<PathBuf> {
if path.is_file() {
Expand Down Expand Up @@ -546,6 +632,94 @@ mod tests {
assert!(result.diagnostics.is_empty());
}

#[test]
fn lint_valid_schema_transition_object() {
let mut file = NamedTempFile::new().unwrap();
writeln!(
file,
r#"{{
"$id": "https://example.com/test.json",
"properties": {{
"legacy_id": {{
"type": "string",
"ucp_request": {{
"update": {{
"transition": {{
"from": "required",
"to": "omit",
"description": "Will be removed in v2."
}}
}}
}}
}}
}}
}}"#
)
.unwrap();

let result = lint_file(file.path(), file.path().parent().unwrap());
assert_eq!(result.status, FileStatus::Ok);
assert!(result.diagnostics.is_empty());
}

#[test]
fn lint_invalid_schema_transition() {
let mut file = NamedTempFile::new().unwrap();
writeln!(
file,
r#"{{
"$id": "https://example.com/test.json",
"properties": {{
"x": {{
"type": "string",
"ucp_request": {{
"transition": {{
"from": "required",
"to": "required",
"description": "from and to must be distinct"
}}
}}
}}
}}
}}"#
)
.unwrap();

let result = lint_file(file.path(), file.path().parent().unwrap());
assert_eq!(result.status, FileStatus::Error);
assert!(result.diagnostics.iter().any(|d| d.code == "E004"));
}

#[test]
fn lint_schema_transition_missing_description() {
let mut file = NamedTempFile::new().unwrap();
writeln!(
file,
r#"{{
"$id": "https://example.com/test.json",
"properties": {{
"x": {{
"type": "string",
"ucp_request": {{
"transition": {{
"from": "required",
"to": "omit"
}}
}}
}}
}}
}}"#
)
.unwrap();

let result = lint_file(file.path(), file.path().parent().unwrap());
assert_eq!(result.status, FileStatus::Error);
assert!(result
.diagnostics
.iter()
.any(|d| d.code == "E004" && d.message.contains("description")));
}

#[test]
fn lint_invalid_ucp_type() {
let mut file = NamedTempFile::new().unwrap();
Expand Down
Loading
Loading