lutaml-model 0.7.3 → 0.7.5

data/docs/schema_import.adoc

@@ -0,0 +1,364 @@
+= Schema import
+
+This document describes how to import schemas into LutaML models.
+
+== Schema import
+
+=== Overview
+
+Lutaml::Model provides functionality to import schema definitions into LutaML
+models. This allows you to create models from existing schema definitions.
+
+The following figure illustrates the process of importing an XML Schema model to
+create corresponding LutaML models.
+
+.Importing serialization schemas to create LutaML models (XML example)
+[source]
+----
+╔════════════════════════════╗                        ╔═══════════════════════╗
+║    Serialization Models    ║                        ║       Core Model      ║
+╚════════════════════════════╝                        ╚═══════════════════════╝
+
+╭┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╮                        ╭┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╮
+┆  XML Schema (XSD/RNG/RNC)  ┆                        ┆          Model        ┆
+┆              │             ┆   ┌────────────────┐   ┆            │          ┆
+┆       ┌──────┴──────┐      ┆   │                │   ┆   ┌────────┴──┐       ┆
+┆       │             │      ┆   │    Schema      │   ┆   │           │       ┆
+┆    Models      Value Types ┆──►│   Importing    │──►┆ Models   Value Types  ┆
+┆       │             │      ┆   │                │   ┆   │           │       ┆
+┆       │             │      ┆   └────────────────┘   ┆   │           │       ┆
+┆  ┌────┴────┐      ┌─┴─┐    ┆           │            ┆   │    ┌──────┴──┐    ┆
+┆  │         │      │   │    ┆           │            ┆   │    │         │    ┆
+┆ Element  Value  xs:string  ┆           │            ┆   │   String  Integer ┆
+┆ Attribute Type  xs:date    ┆           │            ┆   │   Date    Float   ┆
+┆ Union  Complex  xs:boolean ┆           │            ┆   │   Time    Boolean ┆
+┆ Sequence Choice xs:anyURI  ┆           │            ┆   │                   ┆
+╰┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╯           │            ┆   └──────┐            ┆
+                                         │            ┆          │            ┆
+                                         │            ┆     Contains          ┆
+                                         │            ┆     more Models       ┆
+                                         │            ┆     (recursive)       ┆
+                                         │            ┆                       ┆
+                                         │            ╰┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╯
+                                         │            ┌────────────────┐
+                                         │            │                │
+                                         │            │     Model      │
+                                         └──────────► │ Transformation │
+                                                      │       &        │
+                                                      │ Mapping Rules  │
+                                                      │                │
+                                                      └────────────────┘
+----
+
+
+Currently, the following schema formats are supported for import:
+
+* XSD (https://w3.org/TR/xmlschema-1/[XML Schema Definition Language])
+
+=== XML Schema (XSD) import
+
+W3C XSD is a schema language designed to define the structure of XML documents,
+alongside other XML schema languages like DTD, RELAX NG, and Schematron.
+
+Lutaml::Model supports the import of XSD schema files to define information
+models that can be used to parse and generate XML documents.
+
+Specifically, the `Lutaml::Model::Schema#from_xml` method loads XML Schema files
+(XSD, `*.xsd`) and generates Ruby files (`*.rb`) that inherit from
+`Lutaml::Model::Serializable` that are saved to disk.
+
+==== Syntax
+
+[source,ruby]
+----
+Lutaml::Model::Schema.from_xml(
+  xsd_schema, <1>
+  options: options <2>
+)
+----
+<1> The `xsd_schema` is the XML Schema string to be converted to model files.
+<2> The `options` hash is an optional argument.
+
+`options`:: Optional hash containing potentially the following key-values.
+
+`output_dir`::: The directory where the model files will be saved. If not
+provided, a default directory named `lutaml_models_<timestamp>` is created.
++
+[example]
+`"path/to/directory"`
+
+`create_files`::: A `boolean` argument (`false` by default) to create files
+directly in the specified directory as defined by the `output_dir` option.
++
+[example]
+`create_files: (true | false)`
+
+`load_classes`::: A `boolean` argument (`false` by default) to load generated
+classes before returning them.
++
+[example]
+`load_classes: (true | false)`
+
+`namespace`::: The namespace of the schema. This will be added in the
+`Lutaml::Model::Serializable` file's `xml do` block.
++
+[example]
+`http://example.com/namespace`
+
+`prefix`::: The prefix of the namespace provided in the `namespace` option.
++
+[example]
+`example-prefix`
+
+`location`::: The URL or path of the directory containing all the files of the
+schema. For more information, refer to the
+link:https://www.w3.org/TR/xmlschema-1/#include[XML Schema specification].
++
+[example]
+`"http://example.com/example.xsd"`
++
+[example]
+`"path/to/schema/directory"`
+
+NOTE: If both `create_files` and `load_classes` are provided, the `create_files`
+argument will take priority and generate files without loading them!
+
+==== Generated model structure
+
+The generated LutaML models consists of two different kind of Ruby classes
+depending on the XSD schema:
+
+XSD "SimpleTypes":: converted into classes that inherit from
+`Lutaml::Model::Type::Value`, which define the data types with restrictions and
+other validations of these values.
+
+XSD "ComplexTypes":: converted into classes that inherit from
+`Lutaml::Model::Serializable` that model according to the defined structure.
+
+Lutaml::Model uses the https://github.com/lutaml/lutaml-xsd[`lutaml-xsd` gem] to
+automatically resolve the `include` and `import` elements, enabling
+*Lutaml-Model* to generate the corresponding model files.
+
+This auto-resolving feature allows seamless integration of these files into your
+models without the need for manual resolution of includes and imports.
+
+==== Example
+
+[example]
+====
+[source,ruby]
+----
+xsd_schema = <<~XSD
+  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+    <!-- XML schema definition here -->
+    <xs:element name="User">
+      <xs:complexType>
+        <xs:sequence>
+          <xs:element name="id" type="xs:positiveInteger"/>
+          <xs:element name="age" type="xs:positiveInteger"/>
+          <xs:element name="token" type="xs:token"/>
+        </xs:sequence>
+      </xs:complexType>
+    </xs:element>
+  </xs:schema>
+XSD
+
+options = {
+  # These are all optional:
+  output_dir: 'path/to/directory',
+  namespace: 'http://example.com/namespace',
+  prefix: "example-prefix",
+  location: "http://example.com/example.xsd",
+  # or
+  # location: "path/to/schema/directory"
+  create_files: true, # Default: false
+  # OR
+  load_classes: true, # Default: false
+}
+
+# generates the files in the output_dir | default_dir
+Lutaml::Model::Schema.from_xml(xsd_schema, options: options)
+----
+====
+
+==== Working with generated models
+
+You can use the models directly if you set `load_classes: true`:
+
+[example]
+====
+[source,ruby]
+----
+# Generate and load the models
+Lutaml::Model::Schema.from_xml(xsd_schema, options: {load_classes: true})
+
+# Create a new User instance
+user = User.new(id: 1112, age: 29, token: "u9dId901dp13f")
+
+# Serialize to XML
+xml = user.to_xml
+# => "<User>\n  <id>1112</id>\n  <age>29</age>\n  <token>u9dId901dp13f</token>\n</User>"
+
+# Parse from XML
+parsed_user = User.from_xml(xml)
+parsed_user.id # => 1112
+parsed_user.age # => 29
+parsed_user.token # => "u9dId901dp13f"
+----
+====
+
+Alternatively, you could directly load the generated Ruby files into your application by
+requiring them:
+
+[example]
+====
+[source,ruby]
+----
+Lutaml::Model::Schema.from_xml(xsd_schema, options: {output_dir: 'path/to/directory', create_files: true})
+require_relative 'path/to/directory/*.rb'
+----
+====
+
+=== JSON/YAML Schema import
+
+Lutaml::Model supports importing JSON Schema definitions to generate Ruby model classes. This enables you to create Ruby models that match your JSON Schema, supporting schema-driven development and interoperability.
+
+==== Overview
+
+The `Lutaml::Model::Schema::JsonSchema.generate_model_classes` method takes a JSON Schema (as a Ruby hash) and generates Ruby class definitions for each schema in the `$defs` section.
+
+- Each generated class inherits from `Lutaml::Model::Serializable`.
+- Attributes are created based on the schema's properties.
+- The output is a hash mapping definition names to Ruby class code (as strings).
+
+==== Usage
+
+[source,ruby]
+----
+require 'lutaml/model/schema/json_schema'
+require 'json'
+
+# Load your JSON Schema (as a Ruby hash)
+schema = JSON.parse(File.read("your_schema.json"))
+
+# Generate Ruby model class definitions as strings
+model_classes = Lutaml::Model::Schema::JsonSchema.generate_model_classes(schema)
+
+# model_classes is a hash mapping definition names to Ruby class code
+puts model_classes["YourDefinitionName"]
+----
+
+==== Example
+
+Given a JSON Schema with a `$defs` section:
+
+[source,json]
+----
+{
+  "$defs": {
+    "Person": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "age": { "type": "integer" }
+      }
+    }
+  }
+}
+----
+
+The generated Ruby class will look like:
+
+[source,ruby]
+----
+class Person < Lutaml::Model::Serializable
+  attribute "name", :string
+  attribute "age", :integer
+end
+----
+
+==== Polymorphic Classes and `oneOf` Support
+
+Polymorphism allows you to define a common interface for multiple classes, enabling them to be used interchangeably. In JSON Schema, polymorphism is often represented using the `oneOf` keyword, which specifies that a value must validate against exactly one of the given schemas.
+
+For example:
+
+[source,json]
+----
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/PolymorphicModel",
+  "$defs": {
+    "PolymorphicModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shape": {
+          "type": ["object", "null"],
+          "oneOf": [
+            { "$ref": "#/$defs/Circle" },
+            { "$ref": "#/$defs/Square" },
+            { "$ref": "#/$defs/Shape" }
+          ]
+        }
+      }
+    },
+    "Circle": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "area": { "type": ["number", "null"] },
+        "radius": { "type": ["number", "null"] }
+      }
+    },
+    "Square": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "area": { "type": ["number", "null"] },
+        "side": { "type": ["number", "null"] }
+      }
+    },
+    "Shape": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "area": { "type": ["number", "null"] }
+      }
+    }
+  }
+}
+----
+
+===== Detecting the Parent Class
+
+When using `oneOf`, you can infer the parent class by identifying the common attributes shared by all referenced schemas. In the example above, all referenced types (`Circle`, `Square`, `Shape`) have an `area` property, so a `Shape` parent class can be defined with this attribute. The subclasses (`Circle`, `Square`) then add their specific attributes.
+
+This pattern allows Lutaml::Model to:
+
+- Detect the parent class by finding the intersection of attributes in all `oneOf` schemas.
+- Generate a base class with the shared attributes.
+- Generate subclasses for each specific schema, inheriting from the base class and adding unique attributes.
+
+===== Example Ruby Mapping
+
+[source,ruby]
+----
+class Shape < Lutaml::Model::Serializable
+  attribute :area, :float
+end
+
+class Circle < Shape
+  attribute :radius, :float
+end
+
+class Square < Shape
+  attribute :side, :float
+end
+
+class PolymorphicModel < Lutaml::Model::Serializable
+  attribute :shape, :Shape, polymorphic: [Circle, Square]
+end
+----
+
+This approach enables polymorphic deserialization and validation, matching the intent of the JSON

data/flake.lock

@@ -0,0 +1,114 @@
+{
+  "nodes": {
+    "devshell": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1735644329,
+        "narHash": "sha256-tO3HrHriyLvipc4xr+Ewtdlo7wM1OjXNjlWRgmM7peY=",
+        "owner": "numtide",
+        "repo": "devshell",
+        "rev": "f7795ede5b02664b57035b3b757876703e2c3eac",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "ref": "main",
+        "repo": "devshell",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1733328505,
+        "narHash": "sha256-NeCCThCEP3eCl2l/+27kNNK7QrwZB1IJCrXfrbv5oqU=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "ff81ac966bb2cae68946d5ed5fc4994f96d0ffec",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1722073938,
+        "narHash": "sha256-OpX0StkL8vpXyWOGUD6G+MA26wAXK6SpT94kLJXo6B4=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "e36e9f57337d0ff0cf77aceb58af4c805472bfae",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1739959802,
+        "narHash": "sha256-WEWM1ylf1XMC355xzf9aUFVUB9SrRexayeTXk8LA7SU=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "d254fd973c0ce7c7c8ae2a4251d9d801368508e3",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "master",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devshell": "devshell",
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs_2"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/flake.nix

@@ -0,0 +1,103 @@
+{
+  description = "Ruby Dev Env";
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/master";
+    flake-utils.url = "github:numtide/flake-utils";
+    devshell.url = "github:numtide/devshell/main";
+    flake-compat = {
+      url = "github:edolstra/flake-compat";
+      flake = false;
+    };
+  };
+  outputs =
+    { self
+    , nixpkgs
+    , flake-utils
+    , devshell
+    , flake-compat
+    , ...
+    }:
+    flake-utils.lib.eachDefaultSystem (system:
+    let
+      cwd = builtins.toString ./.;
+      overlays = map (x: x.overlays.default) [
+        devshell
+      ];
+      pkgs = import nixpkgs { inherit system overlays; };
+    in
+    rec {
+
+      # nix develop
+      devShell = pkgs.devshell.mkShell {
+        env = [
+        ];
+        commands = [
+          {
+            name = "irb";
+            command = "bundle exec irb \"$@\"";
+            help = "Run console IRB (has completion menu)";
+            category = "Ruby";
+          }
+          {
+            name = "console";
+            command = "bundle exec irb \"$@\"";
+            help = "Run console IRB (has completion menu)";
+            category = "Ruby";
+          }
+          {
+            name = "pry";
+            command = "bundle exec pry \"$@\"";
+            help = "Run pry";
+            category = "Ruby";
+          }
+          {
+            name = "release";
+            command = "bundle exec rake release \"$@\"";
+            help = "Run rake release, which adds a tag and pushes to RubyGems";
+            category = "Ruby";
+          }
+          {
+            name = "rubocop";
+            command = "bundle exec rubocop \"$@\"";
+            help = "Run rubocop";
+            category = "Ruby";
+          }
+          {
+            name = "lint";
+            command = "bundle exec rubocop \"$@\"";
+            help = "Run rubocop";
+            category = "Ruby";
+          }
+          {
+            name = "rspec";
+            command = "bundle exec rspec \"$@\"";
+            help = "Run test suite";
+            category = "Ruby";
+          }
+          {
+            name = "update-flakes";
+            command = "make update-flakes \"$@\"";
+            help = "Update all flakes";
+            category = "Nix";
+          }
+        ];
+        packages = with pkgs; [
+          bash
+          curl
+          fd
+          # fzf
+          gnused
+          jq
+          nodejs
+          # rubocop
+          # ruby
+          # rubyfmt # Broken
+          rubyPackages.ruby-lsp
+          rubyPackages.solargraph
+          rubyPackages.sorbet-runtime
+          ripgrep
+          wget
+        ];
+      };
+    });
+}