From 707405cfbf37fce729fbbaf2409bf952ea0e92d5 Mon Sep 17 00:00:00 2001 From: Andrew Nolte Date: Mon, 2 Mar 2026 16:25:48 -0500 Subject: [PATCH 1/3] Docs: update with rfl::Deprecated --- README.md | 1 + docs/json_schema.md | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/README.md b/README.md index b400d9a3..319996ac 100644 --- a/README.md +++ b/README.md @@ -367,6 +367,7 @@ struct Person { std::vector> children; float salary; + rfl::Deprecated<"Use Salary Instead", "Wage in dollars", int> wage; }; const std::string json_schema = rfl::json::to_schema(); diff --git a/docs/json_schema.md b/docs/json_schema.md index 6332fd38..a0e92b01 100644 --- a/docs/json_schema.md +++ b/docs/json_schema.md @@ -192,3 +192,56 @@ const std::string json_schema = rfl::json::to_schema< } } ``` + +## Indicating deprecated fields + +You can mark fields as deprecated in the JSON schema using `rfl::Deprecated`. This adds `"deprecated": true` and a `"deprecationMessage"` to the generated schema, along with a description. + +`rfl::Deprecated` takes three template parameters: a deprecation message, a description, and the underlying type: + +```cpp +struct Person { + rfl::Deprecated<"Use 'full_name' instead.", "The person's first name", std::string> + first_name; + rfl::Description<"The person's full name", std::string> full_name; + float salary; +}; +``` + +```cpp +const std::string json_schema = rfl::json::to_schema(rfl::json::pretty); +``` + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$ref": "#/$defs/Person", + "$defs": { + "Person": { + "type": "object", + "properties": { + "first_name": { + "type": "string", + "description": "The person's first name", + "deprecated": true, + "deprecationMessage": "Use 'full_name' instead." + }, + "full_name": { + "type": "string", + "description": "The person's full name" + }, + "salary": { + "type": "number" + } + }, + "required": [ + "first_name", + "full_name", + "salary" + ] + } + } +} +``` + +`rfl::Deprecated` behaves like a thin wrapper around the underlying type, just like `rfl::Description`. You can access the underlying value using `.get()`, `.value()`, `operator()()`, or the assignment operator. From 0817e2fa9c1f96a9b9e7af6379a5078537c0d329 Mon Sep 17 00:00:00 2001 From: Andrew Nolte Date: Mon, 2 Mar 2026 16:42:04 -0500 Subject: [PATCH 2/3] Update docs/json_schema.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/json_schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/json_schema.md b/docs/json_schema.md index a0e92b01..78069001 100644 --- a/docs/json_schema.md +++ b/docs/json_schema.md @@ -201,7 +201,7 @@ You can mark fields as deprecated in the JSON schema using `rfl::Deprecated`. Th ```cpp struct Person { - rfl::Deprecated<"Use 'full_name' instead.", "The person's first name", std::string> + rfl::Deprecated<"Use 'full_name' instead.", "The person's first name", std::optional> first_name; rfl::Description<"The person's full name", std::string> full_name; float salary; From 3816543cdbe13853af745775bf6774a7f2e22dcb Mon Sep 17 00:00:00 2001 From: Andrew Nolte Date: Mon, 2 Mar 2026 16:46:09 -0500 Subject: [PATCH 3/3] make deprecated types used in docs wrapped in optional --- README.md | 4 ++-- docs/json_schema.md | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 319996ac..9ac863e0 100644 --- a/README.md +++ b/README.md @@ -367,7 +367,7 @@ struct Person { std::vector> children; float salary; - rfl::Deprecated<"Use Salary Instead", "Wage in dollars", int> wage; + rfl::Deprecated<"Use Salary Instead", "Wage in dollars", std::optional> wage; }; const std::string json_schema = rfl::json::to_schema(); @@ -376,7 +376,7 @@ const std::string json_schema = rfl::json::to_schema(); The resulting JSON schema looks like this: ```json -{"$schema":"https://json-schema.org/draft/2020-12/schema","$ref":"#/$defs/Person","$defs":{"Person":{"type":"object","properties":{"children":{"type":"array","description":"The person's children. Pass an empty array for no children.","items":{"$ref":"#/$defs/Person"}},"email":{"type":"string","description":"Must be a proper email in the form xxx@xxx.xxx.","pattern":"^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$"},"first_name":{"type":"string"},"last_name":{"type":"string"},"salary":{"type":"number"}},"required":["children","email","first_name","last_name","salary"]}}} +{"$schema":"https://json-schema.org/draft/2020-12/schema","$ref":"#/$defs/Person","$defs":{"Person":{"type":"object","properties":{"children":{"type":"array","description":"The person's children. Pass an empty array for no children.","items":{"$ref":"#/$defs/Person"}},"email":{"type":"string","description":"Must be a proper email in the form xxx@xxx.xxx.","pattern":"^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$"},"first_name":{"type":"string"},"last_name":{"type":"string"},"salary":{"type":"number"},"wage":{"type":"integer","description":"Wage in dollars","deprecated":true,"deprecationMessage":"Use Salary Instead"}},"required":["children","email","first_name","last_name","salary"]}}} ``` Note that this is currently supported for JSON only, since most other formats do not support schemata in the first place. diff --git a/docs/json_schema.md b/docs/json_schema.md index 78069001..28b24baf 100644 --- a/docs/json_schema.md +++ b/docs/json_schema.md @@ -202,7 +202,7 @@ You can mark fields as deprecated in the JSON schema using `rfl::Deprecated`. Th ```cpp struct Person { rfl::Deprecated<"Use 'full_name' instead.", "The person's first name", std::optional> - first_name; + std::optional; rfl::Description<"The person's full name", std::string> full_name; float salary; }; @@ -235,7 +235,6 @@ const std::string json_schema = rfl::json::to_schema(rfl::json::pretty); } }, "required": [ - "first_name", "full_name", "salary" ]