Convert assembled Smithy models to JSON Schema

smithy

json-schema

moonbit

Download zip

Author

moonrockz

Version

0.6.0

License

Apache-2.0

Repository

github.com/moonrockz/smithy

Last updated

4 hours ago

Downloads

#Smithy JSON Schema

Converts an assembled Smithy model into a JSON Schema document.

#Library

///|
test {
  let loaded = @smithy.Loader::new()
    .add_idl(
      "example.smithy", "$version: \"2\"\nnamespace example\nstructure Value { name: String }",
    )
    .assemble()
  let document = @jsonschema.convert(loaded.model.unwrap())
  assert_true(document is { "definitions": { "Value": _, .. }, .. })
}

Pass service="example#Api" to keep the service's connected value shapes. Services, operations, resources and prelude definitions are omitted. Mixins are flattened before conversion. Simple shapes and lists are inlined where the reference converter inlines them; shared aggregate shapes use $ref. Conflicting exported names and invalid configuration raise JsonSchemaError.

Protocol converters can prepare SchemaIndex::new(model, service~, config~) once, then use document(), shape(id), schema_for_member(id) and structure(id, selected_members) with the same contextual references. Filtering a structure happens before required properties are computed. definition(name) resolves component names within the selected service closure.

Protocol exporters can opt into SchemaIndex::for_values or convert_values. This mode replaces target constraints with explicit member overrides, retains intrinsic integer/float bounds, closes structures, limits unions to exactly one known member, and allows null collection values only where sparse or Document permits them. Shared data and constrained member variants use definitions so recursive collections remain finite. It does not change the reference-compatible defaults. Wire-specific limitations such as decoded blob lengths and timestamp policies still require the exporting protocol's diagnostics and extensions. Value conversion requires union_strategy="oneOf", map_strategy="propertyNames" and support_non_numeric_floats=false. Other settings for these options raise InvalidConfiguration because they discard runtime member, map-key, sparse-value or numeric-bound contracts.

#Build plugin

The Smithy CLI registers the jsonSchema plugin. Put this in smithy-build.json, then run smithy build:

{
  "version": "1.0",
  "sources": ["model"],
  "projections": {
    "schema": {
      "plugins": {
        "jsonSchema": {
          "service": "example#Api",
          "useJsonName": true
        }
      }
    }
  }
}

The document is written to build/smithy/schema/jsonSchema/schema.json.

Plugin setting	Library Config::new argument	Default
useJsonName	use_json_name	false
unionStrategy	union_strategy	oneOf; also object, structure
enumStrategy	enum_strategy	enum; also oneOf
mapStrategy	map_strategy	propertyNames; also patternProperties
defaultTimestampFormat	default_timestamp_format	date-time; also http-date, epoch-seconds
supportNonNumericFloats	support_non_numeric_floats	false
definitionPointer	definition_pointer	#/definitions
schemaDocumentExtensions	schema_document_extensions	{}
addReferenceDescriptions	add_reference_descriptions	false
disableDefaultValues	disable_default_values	false
disableIntEnums	disable_int_enums	false
useIntegerType	use_integer_type	false
alphanumericOnlyRefs	alphanumeric_only_refs	false; sanitize names before collision detection

definitionPointer starts with #/ and supports nested paths such as #/components/schemas. As in the reference, pointer escaping is unsupported. The plugin's jsonSchemaVersion accepts draft07 or draft2020-12; the latter defaults the definition pointer to #/$defs.

JsonSchemaError

source

pub(all) suberror JsonSchemaError {
  ConflictingShapeName(String)
  InvalidConfiguration(String)
} derive(@moonbitlang/core/debug.Debug
Debug)

Config

source

pub(all) struct Config {
  map_strategy : String
  union_strategy : String
  enum_strategy : String
  use_json_name : Bool
  default_timestamp_format : String
  support_non_numeric_floats : Bool
  schema_document_extensions : Json
  definition_pointer : String
  add_reference_descriptions : Bool
  disable_default_values : Bool
  disable_int_enums : Bool
  use_integer_type : Bool
  alphanumeric_only_refs : Bool
}

Conversion settings shared with the JSON Schema build plugin.

Config::new

source

fn Config::new(map_strategy? : String, union_strategy? : String, enum_strategy? : String, use_json_name? : Bool, default_timestamp_format? : String, support_non_numeric_floats? : Bool, schema_document_extensions? : Json, definition_pointer? : String, add_reference_descriptions? : Bool, disable_default_values? : Bool, disable_int_enums? : Bool, use_integer_type? : Bool, alphanumeric_only_refs? : Bool) -> Config

SchemaIndex

source

pub struct SchemaIndex {
  shapes : Map[String, Json]
  names : Map[String, String]
  config : Config
  document : Json
  definitions : Map[String, @moonrockz/smithy.ShapeId
ShapeId]
  // private fields
}

A prepared conversion context for protocol converters that need the complete schema document plus schemas for individual members or filtered structures. The encoded model and contextual names are prepared once, not per binding.

SchemaIndex::definition

source

fn SchemaIndex::definition(self : SchemaIndex, name : String) -> @moonrockz/smithy.ShapeId
ShapeId?

Resolve a contextual component name within the selected service closure.

SchemaIndex::document

source

fn SchemaIndex::document(self : SchemaIndex) -> Json

SchemaIndex::for_values

source

fn SchemaIndex::for_values(model : @moonrockz/smithy.Model
Model, service? : String, config? : Config) -> SchemaIndex raise

Prepare value-compatible schemas without changing reference conversion.

SchemaIndex::name

source

fn SchemaIndex::name(self : SchemaIndex, id : @moonrockz/smithy.ShapeId
ShapeId) -> String

SchemaIndex::new

source

fn SchemaIndex::new(model : @moonrockz/smithy.Model
Model, service? : String, config? : Config) -> SchemaIndex raise

SchemaIndex::schema_for_member

source

fn SchemaIndex::schema_for_member(self : SchemaIndex, id : @moonrockz/smithy.ShapeId
ShapeId, config? : Config?) -> Json raise JsonSchemaError

Convert a member using the same inline/reference rules as a full document.

SchemaIndex::shape

source

fn SchemaIndex::shape(self : SchemaIndex, id : @moonrockz/smithy.ShapeId
ShapeId, config? : Config?) -> Json raise JsonSchemaError

Convert a value shape inline, retaining the shared contextual references.

SchemaIndex::structure

source

fn SchemaIndex::structure(self : SchemaIndex, id : @moonrockz/smithy.ShapeId
ShapeId, selected : Array[@moonrockz/smithy.ShapeId
ShapeId]) -> Json raise JsonSchemaError

Convert only the selected members of a structure. Filtering occurs before required/property generation, so omitted HTTP bindings cannot leave stale required properties in synthesized document payloads.

convert

source

fn convert(model : @moonrockz/smithy.Model
Model, service? : String, config? : Config) -> Json raise

Convert value shapes in an assembled model to a JSON Schema document.

convert_values

source

fn convert_values(model : @moonrockz/smithy.Model
Model, service? : String, config? : Config) -> Json raise

Convert with runtime value-contract semantics while retaining the existing reference-compatible convert signature and Config record.

Source Files

Site source Report issue Packages Build queue Skills Statistics

smithy-jsonschema

#Smithy JSON Schema

#Library

#Build plugin

#JsonSchemaError

#Config

#Config::new

#SchemaIndex

#SchemaIndex::definition

#SchemaIndex::document

#SchemaIndex::for_values

#SchemaIndex::name

#SchemaIndex::new

#SchemaIndex::schema_for_member

#SchemaIndex::shape

#SchemaIndex::structure

#convert

#convert_values

Source Files

JsonSchemaError

Config

Config::new

SchemaIndex

SchemaIndex::definition

SchemaIndex::document

SchemaIndex::for_values

SchemaIndex::name

SchemaIndex::new

SchemaIndex::schema_for_member

SchemaIndex::shape

SchemaIndex::structure

convert

convert_values