Extensions

Extensions are integral part of SDC, allowing developers to enhance the data model provided with additional information. protoSDC supports extensions using the [Any](https://protobuf.dev/programming-guides/proto3/#any) well-known type.

Specifying Extensions

protoSDC Converter supports generating both standalone extensions as well as extensions that reference elements from the BICEPS data model.

Generating the BICEPS data model using proto-converter produces a file called an Episode, which contains information about the generated model. This file can be used in subsequent executions of proto-converter to allow newly generated output to reference the already generated data model.

Take this example:

 1<?xml version="1.0" encoding="UTF-8" ?>
 2<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:example="urn:oid:1.2.3.4.5" xmlns:extension="urn:oid:1.2.3.4.6" targetNamespace="urn:oid:1.2.3.4.6" elementFormDefault="qualified" attributeFormDefault="unqualified" xml:lang="en">
 3    <xsd:import namespace="urn:oid:1.2.3.4.5" schemaLocation="example.xsd"/>
 4
 5    <xsd:element name="ExtensionElement" type="extension:ExtensionType"/>
 6
 7    <xsd:complexType name="ExtensionType">
 8        <xsd:sequence>
 9            <xsd:element name="BooleanElement" type="example:BooleanContentType"/>
10<!--            <xsd:element ref="example:SimpleContentExtension"/>-->
11        </xsd:sequence>
12        <xsd:attribute name="AnAttribute" type="xsd:string"/>
13        <xsd:attributeGroup ref="example:MyFancyAttributeGroup"/>
14    </xsd:complexType>
15
16
17</xsd:schema>

It imports a schema for which we might already have a generated data model and we do not want to generate it again. If so, we can configure the proto-converter to associate all references to example.xsd by changing our configuration to load the episode for example.xsd.

 1[Converter.General]
 2# the schema file to load
 3schemaFile = "../example_schemas/example_extension.xsd"
 4# limit of iterations for resolving inheritance in the xml schema
 5loopThreshold = 1000
 6# location from which to load episode files
 7episodeLocationIn = "../episode_out.json"
 8# location in which to store episode files
 9#episodeLocationOut = "../episode_out.json"
10# suffix to use for attributes to avoid collision between XML element fields and XML element attribute names
11attributeSuffix = "Attr"
12# root folder in which to generate output. Generators will produce sub-folders
13outputFolder = "../generated/"

This tells the converter to enhance the data model with data from the episode_out.json file, which contains the references to the existing example.xsd data model.

Extension best practices

proto-converter only supports a subset of XML schema. For compatibility purposes, follow these rules:

  • no xsd:any

  • no xsd:anyAttribute

  • no nested extensions

  • …