diff --git a/docs/converters/json-schema.md b/docs/converters/json-schema.md index 1e18c3a..9472a13 100644 --- a/docs/converters/json-schema.md +++ b/docs/converters/json-schema.md @@ -10,7 +10,17 @@ parent: "Converters" 1. TOC {:toc} -Recap uses the `JSONSchemaConverter` class to convert between Recap types and JSON Schema types. `JSONSchemaConverter` has one main method: `to_recap`. +Recap uses the `JSONSchemaConverter` class to convert between Recap types and JSON Schema types. `JSONSchemaConverter` has two main methods: `to_recap` and `from_recap`. + +## `from_recap` + +This method converts a Recap type to a JSON Schema. + +```python +def from_recap(self, recap_type: RecapType) -> dict[str, Any]: +``` + +The `from_recap` method takes a Recap type as input and recursively converts it into an equivalent JSON Schema. The returned JSON schema will have a `"$defs"` key containing any aliased types. ## `to_recap` @@ -24,8 +34,25 @@ The `to_recap` method takes a JSON Schema as a string input, parses it, and tran ## Examples -### JSON Schema to Recap +### Recap to JSON Schema +```python +from recap.converters.json_schema import JSONSchemaConverter +from recap.types import StructType, StringType, IntType + +# Define a Recap schema +recap_schema = StructType( + fields=[ + StringType(name="name"), + IntType(name="age", bits=32), + ] +) + +# Convert to JSON Schema +json_schema = JSONSchemaConverter().from_recap(recap_schema) +``` + +### JSON Schema to Recap ```python from recap.converters.json_schema import JSONSchemaConverter @@ -51,20 +78,43 @@ recap_schema = JSONSchemaConverter().to_recap(json_schema) ## Type Conversion +### From Recap to JSON Schema + +This table shows the corresponding JSON Schema types for each Recap type. + +| Recap Type | JSON Schema Type | +|------------------------------------|------------------| +| NullType | null | +| BoolType | boolean | +| IntType | integer | +| FloatType | number | +| StringType | string | +| BytesType | string (format: byte) | +| ListType | array | +| MapType | object (with "additionalProperties") | +| UnionType | oneOf | +| StructType | object | +| EnumType | string (with "enum" constraint) | + +### From JSON Schema to Recap + This table shows the corresponding Recap types for each JSON Schema type. | JSON Schema Type | Recap Type | |------------------|------------| -| object | StructType | -| array | ListType | +| null | NullType | +| boolean | BoolType | +| integer | IntType(bits=32) | +| number | FloatType(bits=64) | | string (date format) | StringType (with `org.iso.8601.Date` date logical type) | | string (date-time format) | StringType (with `org.iso.8601.DateTime` datetime logical type) | | string (time format) | StringType (with `org.iso.8601.Time` logical type) | | string | StringType(bytes=9_223_372_036_854_775_807, variable=True) | -| number | FloatType(bits=64) | -| integer | IntType(bits=32) | -| boolean | BoolType | -| null | NullType | +| string (byte format) | BytesType | +| array | ListType | +| object (with "additionalProperties") | MapType | +| object | StructType | +| string (with "enum" constraint) | EnumType | ## Limitations and Constraints @@ -72,4 +122,6 @@ JSON Schema types have some restrictions in conversion to Recap types: - The main `to_recap` function requires the root JSON schema to be an object (i.e., a `StructType` in Recap). - Only supports the conversion of JSON Schema primitive types (null, boolean, object, array, number, string, and integer). -- Unsupported JSON Schema constructs will raise a `ValueError`. \ No newline at end of file +- Unsupported JSON Schema constructs will raise a `ValueError`. +- Logical types are ignored in from_recap. +- Many more complex constraints and JSON schema features (like anchors, dynamicAnchors, and so on) are not supported. \ No newline at end of file diff --git a/index.md b/index.md index 5a66bf3..bb1acde 100644 --- a/index.md +++ b/index.md @@ -24,15 +24,15 @@ Recap is a Python library that reads and writes schemas from web services, datab | Format | Read | Write | | ----------- | ----------- | ----------- | -| [Avro](https://recap.build/docs/converters/avro/) | ✅ | ✅ | -| [Protobuf](https://recap.build/docs/converters/protobuf/) | ✅ | ✅ | -| [JSON Schema](https://recap.build/docs/converters/json-schema/) | ✅ | | -| [Snowflake](https://recap.build/docs/readers/snowflake/) | ✅ | | -| [PostgreSQL](https://recap.build/docs/readers/postgresql/) | ✅ | | -| [MySQL](https://recap.build/docs/readers/mysql/) | ✅ | | -| [BigQuery](https://recap.build/docs/readers/bigquery/) | ✅ | | -| [Confluent Schema Registry](https://recap.build/docs/readers/confluent-schema-registry/) | ✅ | | -| [Hive Metastore](https://recap.build/docs/readers/hive-metastore/) | ✅ | | +| [Avro](/docs/converters/avro/) | ✅ | ✅ | +| [Protobuf](/docs/converters/protobuf/) | ✅ | ✅ | +| [JSON Schema](/docs/converters/json-schema/) | ✅ | ✅ | +| [Snowflake](/docs/readers/snowflake/) | ✅ | | +| [PostgreSQL](/docs/readers/postgresql/) | ✅ | | +| [MySQL](/docs/readers/mysql/) | ✅ | | +| [BigQuery](/docs/readers/bigquery/) | ✅ | | +| [Confluent Schema Registry](/docs/readers/confluent-schema-registry/) | ✅ | | +| [Hive Metastore](/docs/readers/hive-metastore/) | ✅ | | ## Supported Types