|
| 1 | +# Runtime Schema Generation |
| 2 | + |
| 3 | +The `Opc.Ua.Core.Schema` library generates schemas for OPC UA data types at runtime. It works for the encodeable types emitted by the source generators and for complex types that are added dynamically by the complex-type client. Schemas are produced in every supported encoding: |
| 4 | + |
| 5 | +- **XSD** for the XML encoding. |
| 6 | +- **BSD** (OPC Binary, Part 6) for the binary encoding. |
| 7 | +- **JSON Schema** (Part 6 Annex C, draft 2020-12) for the JSON encoding, in both the **compact** (reversible, BrowseName-keyed) and **verbose** flavors. |
| 8 | + |
| 9 | +Schemas are built as strongly-typed object models in code — there are no embedded schema strings — so unused generation paths are trimmed away and the whole library is NativeAOT compatible. The XSD object model is the in-box `System.Xml.Schema.XmlSchema`, the BSD object model is the existing `Opc.Ua.Schema.Binary.TypeDictionary`, and the JSON object model is `System.Text.Json.Nodes.JsonObject`. |
| 10 | + |
| 11 | +## Concepts |
| 12 | + |
| 13 | +Generation is driven by a type's runtime structure definition (`StructureDefinition` or `EnumDefinition`), which already captures every field, data type, value rank and optionality. The pieces fit together as follows: |
| 14 | + |
| 15 | +- `ISchemaProvider` is the entry point. It produces an `IUaSchema` for a requested `UaSchemaFormat` and `UaSchemaScope`. |
| 16 | +- `IUaSchema` is the generated document. It exposes the strongly-typed object model (for example `JsonSchemaDocument.Root`, `XmlSchemaDocument.Schema`, `BinarySchemaDocument.Dictionary`) and can serialize itself with `WriteTo(Stream)`, `WriteTo(TextWriter)` or `ToSchemaString()`. |
| 17 | +- `IDataTypeDefinitionResolver` maps a data type id to its `UaTypeDescription` (the type id, browse name and definition). The default implementation, `DataTypeDefinitionRegistry`, is an in-memory registry that generated and dynamically built types register their definitions with. The resolver is also used to follow field references and to enumerate the types of a namespace. |
| 18 | + |
| 19 | +`UaSchemaFormat` selects the encoding (`Xsd`, `Bsd`, `JsonCompact`, `JsonVerbose`). `UaSchemaScope` selects the document granularity: `Type` produces a document for a single type and the closure of the types it depends on; `Namespace` produces a dictionary document for all types in a namespace. |
| 20 | + |
| 21 | +## Registration |
| 22 | + |
| 23 | +The services are registered through the standard OPC UA dependency-injection surface: |
| 24 | + |
| 25 | +```csharp |
| 26 | +IServiceProvider services = new ServiceCollection() |
| 27 | + .AddOpcUa() |
| 28 | + .AddSchemaGeneration() |
| 29 | + .Services |
| 30 | + .BuildServiceProvider(); |
| 31 | + |
| 32 | +ISchemaProvider provider = services.GetRequiredService<ISchemaProvider>(); |
| 33 | +``` |
| 34 | + |
| 35 | +The provider can also be constructed directly when dependency injection is not used: |
| 36 | + |
| 37 | +```csharp |
| 38 | +var registry = new DataTypeDefinitionRegistry(); |
| 39 | +registry.Add(new UaTypeDescription(typeId, browseName, structureDefinition, namespaceUri)); |
| 40 | + |
| 41 | +ISchemaProvider provider = new DefaultSchemaProvider( |
| 42 | + registry, |
| 43 | + new IUaSchemaGenerator[] { new JsonSchemaGenerator() }); |
| 44 | +``` |
| 45 | + |
| 46 | +## Registering data types |
| 47 | + |
| 48 | +Schema generation needs the runtime definition of a type. A type's `StructureDefinition` / `EnumDefinition` is registered with the resolver from whichever source has it: |
| 49 | + |
| 50 | +- **Server / browsed types** — a `DataTypeNode` obtained from a server (or the client node cache) carries its definition in `DataTypeNode.DataTypeDefinition`. Register it directly: |
| 51 | + |
| 52 | +```csharp |
| 53 | +var registry = serviceProvider.GetRequiredService<DataTypeDefinitionRegistry>(); |
| 54 | +registry.TryAddDataType(dataTypeNode, session.NamespaceUris); |
| 55 | +``` |
| 56 | + |
| 57 | +- **Source-generated types** — the generated types expose their definition through the generated `DataTypeDefinitions.Create<TypeName>(namespaceUris)` factory. Wrap it in a `UaTypeDescription` and add it: |
| 58 | + |
| 59 | +```csharp |
| 60 | +registry.Add(new UaTypeDescription(typeId, browseName, definition, namespaceUri)); |
| 61 | +``` |
| 62 | + |
| 63 | +- **Dynamic complex types** — complex types built by the complex-type client carry a `StructureDefinition` (via `IStructureTypeInfo` / the structure-definition attribute) that can likewise be wrapped in a `UaTypeDescription` and registered. |
| 64 | + |
| 65 | +Once registered, fields that reference other registered types are resolved automatically and included in the generated document. |
| 66 | + |
| 67 | +## Generating a schema |
| 68 | + |
| 69 | +Once a type's definition is registered with the resolver, a schema can be produced from its type id: |
| 70 | + |
| 71 | +```csharp |
| 72 | +if (provider.TryGetSchema(typeId, UaSchemaFormat.JsonCompact, UaSchemaScope.Type, out IUaSchema? schema)) |
| 73 | +{ |
| 74 | + string json = schema.ToSchemaString(); |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +The convenience extension methods read more naturally and make a type "expose" its schema: |
| 79 | + |
| 80 | +```csharp |
| 81 | +IUaSchema xsd = provider.GetXmlSchema(type); |
| 82 | +IUaSchema bsd = provider.GetBinarySchema(type); |
| 83 | +IUaSchema jsonCompact = provider.GetJsonSchema(type); |
| 84 | +IUaSchema jsonVerbose = provider.GetJsonSchema(type, verbose: true); |
| 85 | + |
| 86 | +// Resolve by type id and produce JSON in one call. |
| 87 | +provider.TryGetJsonSchema(typeId, out IUaSchema? schema); |
| 88 | +``` |
| 89 | + |
| 90 | +## Working with the object model |
| 91 | + |
| 92 | +Because the schema is an object model, callers can inspect or post-process it before serializing. For JSON: |
| 93 | + |
| 94 | +```csharp |
| 95 | +var document = (JsonSchemaDocument)provider.GetJsonSchema(type); |
| 96 | +JsonObject root = document.Root; // the draft 2020-12 schema |
| 97 | +document.WriteTo(stream); // UTF-8, indented |
| 98 | +``` |
| 99 | + |
| 100 | +## JSON encoding notes (Part 6) |
| 101 | + |
| 102 | +The JSON schemas follow the Part 6 JSON encoding faithfully, matching what the stack's `JsonEncoder` produces: |
| 103 | + |
| 104 | +- `Int64` and `UInt64` are encoded as JSON strings (to avoid precision loss), so they are typed as `string`. |
| 105 | +- `Float`/`Double` accept the special string values `Infinity`, `-Infinity` and `NaN`, so they are typed as `["number", "string"]`. |
| 106 | +- `ByteString` is a base64 `string`; `DateTime` is a `date-time` string; `Guid` is a `uuid` string. |
| 107 | +- The standard structured built-ins (`NodeId`, `Variant`, `ExtensionObject`, `DataValue`, ...) are described once per document in the `$defs` section and referenced. |
| 108 | +- Compact enums are integers (with the allowed values listed via `oneOf`); verbose enums are the `Name_Value` strings. |
| 109 | + |
| 110 | +## PubSub schemas |
| 111 | + |
| 112 | +The `Opc.Ua.PubSub.Schema` library generates JSON Schemas for the PubSub JSON message formats. It is registered with `services.AddOpcUa().AddPubSubSchema()` and exposes `IPubSubSchemaProvider`: |
| 113 | + |
| 114 | +- `CreateDataSetSchema(metaData, fieldContentMask, verbose)` — the per-DataSet payload object, one property per `FieldMetaData`. The field value shape follows the same Part 6 JSON rules as the core library, and `DataSetFieldContentMask` controls whether each field is the raw value or a `DataValue` object (with the mask-selected `StatusCode` / `SourceTimestamp` / ... members). |
| 115 | +- `CreateDataSetMessageSchema(metaData, messageContentMask, fieldContentMask, verbose)` — a single DataSetMessage whose header fields are gated by `JsonDataSetMessageContentMask` and whose `Payload` is the DataSet schema above. |
| 116 | +- `CreateNetworkMessageSchema(metaData, networkContentMask, messageContentMask, fieldContentMask, verbose)` — the `ua-data` NetworkMessage envelope, gated by `JsonNetworkMessageContentMask`; `Messages` is an array of DataSetMessage schemas, or a single object when `SingleDataSetMessage` is set. |
| 117 | +- `CreateMetaDataMessageSchema(metaData, verbose)` — the `ua-metadata` message. |
| 118 | + |
| 119 | +The provider reuses the core `ISchemaProvider` to resolve complex (structured/enum) field data types, embedding them into the document `$defs` section. |
| 120 | + |
| 121 | +## Trimming and NativeAOT |
| 122 | + |
| 123 | +The library opts into `IsAotCompatible` and avoids reflection-based serialization. XSD is written with `System.Xml.Schema.XmlSchema`, BSD with a direct `System.Xml.XmlWriter`, and JSON with `System.Text.Json.Nodes` / `Utf8JsonWriter`. Schema generation is a configuration-time activity, not a hot path; documents are built lazily and can be cached by the caller. Because the generation logic lives in its own assembly, it is trimmed away entirely when an application does not generate schemas. |
0 commit comments