Add JSONSchemaConverter.from_recap docs

gabledata · Aug 15, 2023 · 4bead19 · 4bead19
1 parent c1d3504
commit 4bead19
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 18 deletions.
diff --git 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,25 +78,50 @@ 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
 
 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`.
+- 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.
diff --git 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