Add support for the x-rust-type extension (#584)

Author: ahl

Cargo.lock

@@ -31,29 +31,30 @@ appropriate built-in type based on type attributes. For example, a JSON Schema
 might specify a maximum and/or minimum that indicates the appropriate integral
 type to use.
 
-String schemas that include a `format` are represented with the appropriate Rust
-type. For example `{ "type": "string", "format": "uuid" }` is represented as a
-`uuid::Uuid` (which requires the `uuid` crate be included as a dependency).
+String schemas that include a known `format` are represented with the
+appropriate Rust type. For example `{ "type": "string", "format": "uuid" }` is
+represented as a `uuid::Uuid` (which requires the `uuid` crate be included as a
+dependency).
 
 ### Arrays
 
 JSON Schema arrays can turn into one of three Rust types `Vec<T>`, `HashSet<T>`,
 and tuples depending on the schema properties. An array may have a fixed length
 that matches a fixed list of item types; this is well represented by a Rust
-tuples. The distinction between `Vec<T>` and `HashSet<T>` is only if the
+tuple. The distinction between `Vec<T>` and `HashSet<T>` is only if the
 schema's `uniqueItems` field is `false` or `true` respectively.
 
 ### Objects
 
-In general, objects turn in to Rust structs. If, however, the schema defines no
+In general, objects turn into Rust structs. If, however, the schema defines no
 properties, Typify emits a `HashMap<String, T>` if the `additionalProperties`
 schema specifies `T` or a `HashMap<String, serde_json::Value>` otherwise.
 
-Properties that are not in the `required` set are typically represented as an
-`Option<T>` with the `#[serde(default)]` attribute applied. Non-required
-properties with types that already have a default value (such as a `Vec<T>`)
-simply get the `#[serde(default)]` attribute (so you won't see e.g.
-`Option<Vec<T>>`).
+Properties of generated `struct` that are not in the `required` set are
+typically represented as an `Option<T>` with the `#[serde(default)]` attribute
+applied. Non-required properties with types that already have a default value
+(such as a `Vec<T>`) simply get the `#[serde(default)]` attribute (so you won't
+see e.g. `Option<Vec<T>>`).
 
 ### OneOf
 
@@ -76,6 +77,166 @@ flattened members, this is one of the weaker areas of code generation.
 
 Issues describing example schemas and desired output are welcome and helpful.
 
+## Rust -> Schema -> Rust
+
+Schemas derived from Rust types may include an extension that provides
+information about the original type:
+
+```json
+{
+  "type": "object",
+  "properties": { .. },
+  "x-rust-type": {
+    "crate": "crate-o-types",
+    "version": "1.0.0",
+    "path": "crate_o_types::some_mod::SomeType"
+  }
+}
+```
+
+The extension includes the name of the crate, a Cargo-style version
+requirements spec, and the full path (that must start with ident-converted name
+of the crate).
+
+Each of the modes of using typify allow for a list of crates and versions to be
+specified. In this case, if the user specifies "[email protected]" for
+example, then typify would use its `SomeType` type rather than generating one
+according to the schema.
+
+### Using types from other crates
+
+Each mode of using typify has a method for controlling the use of types with
+`x-rust-type` annotations. The default is to ignore them. The recommended
+method is to specify each crate and version you intend to use. You can
+additionally supply the `*` version for crates (which may result in
+incompatibilities) or you can define a policy to allow the use of all "unknown"
+crates (which may require that addition of dependencies for those crates).
+
+For the CLI:
+```console
+$ cargo typify --unknown-crates allow --crate [email protected] ...
+```
+
+For the builder:
+```rust
+let mut settings = typify::TypeSpaceSettings::default();
+settings.with_unknown_crates(typify::UnknownPolicy::Allow)
+    .with_crate("oxnet", typify::CrateVers::Version("1.0.0".parse().unwrap()));
+```
+
+For the macro:
+```rust
+typify::import_types!(
+  schema = "schema.json",
+  unknown_types = Allow,
+  crates {
+    "oxnet" = "1.0.0"
+  }
+)
+```
+
+### Version requirements
+
+The `version` field within the `x-rust-type` extension follows the Cargo
+version requirements specification. If the extension specifies `0.1.0` of a
+crate and the user states that they're using `0.1.1`, then the type is used;
+conversely, if the extension specifies `0.2.2` and the user is only using
+`0.2.0` the type is not used.
+
+Crate authors may choose to adhere to greater stability than otherwise provided
+by semver. If the extension version is `>=0.1.0, <1.0.0` then the crate author
+is committing to the schema compatibility of the given type on all releases
+until `1.0.0`. It is important that crate authors populate the `version` field
+in a way that upholds type availability. For example, while `*` is a valid
+value, it is only conceivably valid if the type in question were available in
+the first ever version of a crate published and never changed incompatibly in
+any subsequent version.
+
+### Type parameters
+
+The `x-rust-type` extension may also specify type parameters:
+
+```json
+{
+  "$defs": {
+    "Sprocket": {
+      "type": "object",
+      "properties": { .. },
+      "x-rust-type": {
+        "crate": "util",
+        "version": "0.1.0",
+        "path": "util::Sprocket",
+        "parameters": [
+          {
+            "$ref": "#/$defs/Gizmo"
+          }
+        ]
+      }
+    },
+    "Gizmo": {
+      "type": "object",
+      "properties": { .. },
+      "x-rust-type": {
+        "crate": "util",
+        "version": "0.1.0",
+        "path": "util::Gizmo"
+      }
+    }
+  }
+}
+```
+
+With the `[email protected]` crate specified during type generation, schemas
+referencing `#/$defs/Sprocket` would use the (non-generated) type
+`util::Sprocket<util::Gizmo>`.
+
+The `parameters` field is an array of schemas. They may be inline schemas or
+referenced schemas.
+
+### Including `x-rust-type` in your library
+
+The schema for the expected value is as follows:
+
+```json
+{
+  "description": "schema for the x-rust-type extension",
+  "type": "object",
+  "properties": {
+    "crate": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]+$"
+    },
+    "version": {
+      "description": "semver requirements per a Cargo.toml dependencies entry",
+      "type": "string"
+    },
+    "path": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_]+(::[a-zA-Z0-9+]+)*$"
+    },
+    "parameters": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Schema"
+      }
+    }
+  },
+  "required": [
+    "crate",
+    "path",
+    "version"
+  ]
+}
+```
+
+The `version` field expresses the stability of your type. For example, if
+`0.1.0` indicates that `0.1.1` users would be fine whereas `0.2.0` users would
+not use the type (instead generating it). You can communicate a future
+commitment beyond what semver implies by using the [Cargo version requirement
+syntax](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#version-requirement-syntax).
+For example `>=0.1.0, <1.0.0` says that the type will remain structurally
+compatible from version `0.1.0` until `1.0.0`.
+
 ## Formatting
 
 You can format generated code using crates such as
@@ -90,7 +251,7 @@ The examples below show different ways to convert a `TypeSpace` to a string
 ### `rustfmt`
 
 Best for generation of code that might be checked in alongside hand-written
-code such as in the case of an `xtask` or stand-alone code generator (list
+code such as in the case of an `xtask` or stand-alone code generator (such as
 `cargo-typify`).
 
 ```rust

README.md

@@ -18,6 +18,7 @@ clap = { version = "4.5.4", features = ["derive"] }
 color-eyre = "0.6"
 env_logger = "0.10"
 rustfmt-wrapper = "0.2.1"
+semver = "1.0.22"
 serde_json = "1.0.116"
 schemars = "0.8.17"