UA-.NETStandard/docs/Aas.md

OPC UA for Asset Administration Shell (I4AAS)

This repository implements two OPC UA for Asset Administration Shell metamodel generations in one assembly set. They are separate alternatives, not revision levels of one model:

• OPC 30270, "OPC UA for Asset Administration Shell" maps the AAS V2.0.1 metamodel into namespace http://opcfoundation.org/UA/I4AAS/ and lives in Opc.Ua.Aas.V2.
• OPC UA for Asset Administration Shell V3 draft (release 3.00-draft3) maps the AAS V3 draft metamodel into namespace http://opcfoundation.org/UA/I4AAS/v3/ and lives in Opc.Ua.Aas.V3.

The shared root Opc.Ua.Aas namespace contains only code that is genuinely metamodel-neutral: deterministic NodeId encoding and idShortPath handling, AasOptional<T>, digest calculation, materialization diagnostics, the AASX container walk and the value/operation provider contracts.

Project	Purpose
Opc.Ua.Aas	Source-generated I4AAS V2 and V3 models from src/Opc.Ua.Aas/Design, the V2 object model and ingestion readers, the V3 object model and read/write serializers, shared identity/value helpers, materialization diagnostics and AASX container support.
Opc.Ua.Aas.Server	Server-side projection for both metamodels over INodeManagerLifecycle; V2 ingestion materialization and runtime callbacks; V3 registry service, generational materialization, environment export, federation, package integrity and provider contracts.
Opc.Ua.Aas.Client	High-level V2 and V3 clients for deterministic metamodel NodeIds, plus the V3 AAS registry client and typed group/resource clients.
Opc.Ua.Aas.WoT	The V3 informative Annex F bridge between an AAS environment and a WoT Connectivity Thing Description projection.
Opc.Ua.Aas.Tests	NUnit tests for V2 model ingestion/materialization/server/client behavior and V3 model, identity, values, serialization, registry, materialization, packages, federation, DPP and WoT bridge behavior.

The V3 AAS implementation builds on the shared xRegistry registry base and reuses the runtime NodeManager lifecycle described in Runtime NodeSets. V2 is the OPC 30270 metamodel half only: it has no registry, packages, federation, DPP or WoT bridge. The IDTA HTTP API described by Annex G of the V3 draft is intentionally out of scope; this implementation exposes AAS through OPC UA services and, for V3, the xRegistry-compatible registry AddressSpace.

---

Choosing V2 or V3

Host one AAS generation in a server: either V2 or V3. The stack does not enforce that rule at startup, because the two NodeManagers can technically be registered side by side, but the product decision is that a deployment chooses one alternative and exposes one metamodel generation. Running both would publish two different AAS metamodels for the same product domain and leave clients to guess which one is authoritative.

Choose V2 when the published OPC 30270 specification and the AAS V2.0.1 metamodel are the interoperability target. The implementation reads V2 JSON, XML and AASX documents, materializes them into the http://opcfoundation.org/UA/I4AAS/ AddressSpace, serves Read + Write + Call, and publishes the OPC 30270 Table 83 conformance units. It does not export the AddressSpace back to AAS documents, because OPC 30270 does not require a lossless round trip.

Choose V3 when the draft AAS V3 metamodel and everything built on the draft registry half are required: registry, updateable materialization, environment export, packages, package integrity, federation, DPP vocabulary and the WoT bridge. V3 reads and writes JSON, XML and AASX because its draft requires a lossless document/AddressSpace round trip.

---

1. V3 core architecture

The V3 draft companion specification has two independent halves:

• Metamodel half — shells, submodels, concept descriptions and submodel elements are materialized as typed OPC UA nodes, following clauses 6.1 and 6.2. The metamodel surface is Read + Write + Call: value Variables are served through an injectable IAasValueProvider, and AASOperationType.Invoke is served through an injectable IAasOperationHandler.
• Registry half — a catalogue of shell, submodel, concept-description, package and environment documents is served as folders of FileType resources using the xRegistry model (clause 6.5). The registry answers discovery and document-retrieval questions even when the live metamodel tree is hosted elsewhere.

Where both halves are hosted, the stored documents are canonical and the live nodes are derived. A write to a materialized value writes back to the document and bumps a version; a refresh derives a new generation from the document. The default retirement policy is AasProjectionRetirementPolicy.Graceful, so existing monitored items can keep reading the old generation until they drain.

The V3 half also adds the OPC UA Decimal DataType wire encoding needed by clause 6.3.1, and the source generator fix needed for recursive structure DataTypes.

---

2. Shared identity and V3 value fidelity

Deterministic NodeIds and BrowseNames

Clause 6.1.3 assigns deterministic String NodeIds. AasNodeIdEncoding is the public implementation of the reversible, node-kind-discriminated encoding:

string shellId = AasNodeIdEncoding.CreateIdentifiableId(
    AasNodeKind.Shell,
    "https://example.com/aas/42");

string elementId = AasNodeIdEncoding.CreateElementId(
    "https://example.com/submodels/nameplate",
    "Nameplate.ManufacturerName");

if (AasNodeIdEncoding.TryParse(elementId, out AasParsedNodeId parsed))
{
    Console.WriteLine(parsed.IdShortPath);
}

AasIdShortPath builds and parses the metamodel idShortPath convention, and AasBrowseNameAllocator implements the derived BrowseName rule for identifiables that do not carry idShort.

xsd value mapping

AasXsdTypeMap maps every AASDataTypeDefXsdDataType value to exactly one OPC UA DataType, as required by clauses 6.1.2 and 6.3.1. AasLexicalCanonicalizer parses and canonicalizes xsd lexical values, and AasValueSpaceComparer compares values in the XML Schema value space rather than by string equality:

ExpandedNodeId dataTypeId = Opc.Ua.Aas.V3.AasXsdTypeMap.ToDataTypeId(
    Opc.Ua.Aas.V3.AASDataTypeDefXsdDataType.Decimal);

bool parsed = Opc.Ua.Aas.V3.AasLexicalCanonicalizer.TryParse(
    "1.500000",
    Opc.Ua.Aas.V3.AASDataTypeDefXsdDataType.Decimal,
    out Variant value,
    out string? error);

bool equivalent = Opc.Ua.Aas.V3.AasValueSpaceComparer.AreEquivalent(
    "1.500000",
    "1.5",
    Opc.Ua.Aas.V3.AASDataTypeDefXsdDataType.Decimal);

The object model uses AasOptional<T> so absent remains distinct from present-but-empty (clause 6.1.5). Serializers and round-trip comparison preserve that distinction.

---

3. V3 reading, writing and materializing AAS documents

V3 AAS JSON, XML and AASX are read into the same object model. JSON and XML readers return diagnostics instead of throwing for malformed documents:

await using FileStream input = File.OpenRead("environment.json");
Opc.Ua.Aas.V3.AasDocumentReadResult read = await new Opc.Ua.Aas.V3.AasJsonReader()
    .ReadAsync(input, ct);

if (!read.Succeeded)
{
    Console.WriteLine(read.Error);
    return;
}

Opc.Ua.Aas.AasMaterializationResult materialized = Opc.Ua.Aas.V3.AasEnvironmentMaterializer
    .Materialize(read.Environment!);

await using FileStream output = File.Create("environment.aasx");
await new Opc.Ua.Aas.V3.AasxPackageWriter().WriteAsync(output, read.Environment!, ct);

The inverse path serializes a clause 6.1.6 NodeSet back to an AAS environment:

Opc.Ua.Aas.V3.AasSerializationResult serialized = Opc.Ua.Aas.V3.AasEnvironmentSerializer
    .Serialize(materialized.NodeSet);

await using FileStream json = File.Create("roundtrip.json");
await new Opc.Ua.Aas.V3.AasJsonWriter().WriteAsync(json, serialized.Environment, ct);

The round-trip guarantee in clause 6.4 is equivalence, not byte identity. A canonical value rewrite such as "1.500000" to "1.5" is equivalent for xs:decimal; losing digits, conflating absent with empty or changing ordered arrays is not equivalent.

---

4. Hosting the V3 metamodel server

AddAasV3Server registers the environment NodeManager, default providers and the runtime projection host. It must be used with the normal server hosting feature:

services.AddSingleton<IAasValueProvider, MyAasValueProvider>();

services
    .AddOpcUa()
    .AddServer(options =>
    {
        options.EndpointUrls.Add("opc.tcp://localhost:4840/AasServer");
    })
    .Services
    .AddOpcUa()
    .AddAasV3Server(options =>
    {
        options.EnvironmentFolder = "aas-environments";
        options.RetirementPolicy = AasProjectionRetirementPolicy.Graceful;
    })
    .AddOperationHandler<MyAasOperationHandler>();

EnvironmentFolder is read by FolderAasEnvironmentProvider; when it is not set, InMemoryAasEnvironmentProvider is used. The metamodel server can also be constructed directly with AasEnvironmentNodeManagerFactory when an application manages StandardServer.NodeManagerFactories itself.

The runtime uses IAasValueProvider for reads and writes of materialized value Variables:

public sealed class MyAasValueProvider : IAasValueProvider
{
    public ValueTask<AasValueReadResult> ReadValueAsync(
        NodeId valueNodeId,
        CancellationToken cancellationToken = default)
    {
        return new ValueTask<AasValueReadResult>(new AasValueReadResult(
            ServiceResult.Good,
            Variant.From("running"),
            StatusCodes.Good,
            DateTime.UtcNow));
    }

    public ValueTask<ServiceResult> WriteValueAsync(
        NodeId valueNodeId,
        Variant value,
        CancellationToken cancellationToken = default)
    {
        return new ValueTask<ServiceResult>(ServiceResult.Good);
    }
}

IAasOperationHandler.InvokeAsync receives already-marshalled input and in-output values and returns the four outputs required by AASOperationType.Invoke. A failed AAS operation is represented as a Good OPC UA Call with Success = false and a diagnostic, which is distinct from a failed Call service result.

---

5. Using the V3 metamodel client

Opc.Ua.Aas.Client.AasClient computes the deterministic NodeIds of clause 6.1.3, opens the generated *TypeClient proxies, reads values with their declared xsd type and writes lexical values using that type:

var client = new Opc.Ua.Aas.Client.AasClient(session, aasNamespaceIndex, telemetry);

Opc.Ua.Aas.V3.AASPropertyTypeClient temperature = client.OpenProperty(
    "https://example.com/submodels/process",
    "Temperature");

Opc.Ua.Aas.Client.AasValueReadResult current = await client.ReadValueAsync(temperature.ObjectId, ct);
Console.WriteLine($"{current.ValueType}: {current.LexicalValue}");

StatusCode writeStatus = await client.WriteLexicalValueAsync(
    temperature.ObjectId,
    "42.5",
    ct);

Operations keep the OPC UA Call status separate from the AAS success flag:

Opc.Ua.Aas.V3.AASOperationTypeClient reset = client.OpenOperation(
    "https://example.com/submodels/process",
    "Reset");

Opc.Ua.Aas.Client.AasOperationInvokeResult result = await client.InvokeAsync(
    reset.ObjectId,
    ArrayOf<Variant>.Empty,
    ArrayOf<Variant>.Empty,
    0,
    ct);

if (StatusCode.IsGood(result.CallStatusCode) && !result.Success)
{
    Console.WriteLine(result.Diagnostic);
}

Dependency injection registers either a factory over an already connected ManagedSession, or a lazy factory that asks the registered OPC UA client for a session:

services
    .AddOpcUa()
    .AddClient(options => { /* endpoint and application options */ })
    .AddAasV3Client(options =>
    {
        options.InstanceNamespaceUri = "urn:example:aas:instances";
    });

Func<CancellationToken, Task<Opc.Ua.Aas.Client.AasClient>> clientFactory =
    sp.GetRequiredService<Func<CancellationToken, Task<Opc.Ua.Aas.Client.AasClient>>>();
Opc.Ua.Aas.Client.AasClient aas = await clientFactory(ct);

---

6. V3 AAS registry

The V3 AAS registry is a concrete xRegistry specialization (clause 6.5). It exposes the well-known AASRegistry object under Server, projects shell groups, submodel files, concept dictionaries, packages and environment documents, and wires the AAS discovery methods:

• LookupShellsByAssetLink(Name, Value) returns matching shell group NodeIds.
• GetSubmodel(SubmodelIdentifier) returns the document bytes, Format and ContentType, while preserving Bad_UserAccessDenied and Bad_NotFound as meaningful outcomes.

The service keeps immutable snapshots. Every mutation advances Generation, and existing readers keep their previous snapshot:

var registry = new Opc.Ua.Aas.Server.Registry.AasRegistryService();
await registry.UpsertResourceAsync(new Opc.Ua.Aas.Server.Registry.AasUpsertResourceRequest
{
    GroupSourceIdentity = "https://example.com/aas/42",
    ResourceSourceIdentity = "https://example.com/submodels/nameplate",
    GroupKind = Opc.Ua.Aas.Server.Registry.AasRegistryEntityKind.Shell,
    ResourceKind = Opc.Ua.Aas.Server.Registry.AasRegistryEntityKind.Submodel,
    Content = ByteString.From(File.ReadAllBytes("nameplate.json")),
    ContentType = "application/aas+json",
    Format = "aas/3.0+json"
});

Opc.Ua.Aas.Server.Registry.AasGetSubmodelResult document = await registry.GetSubmodelAsync(
    "https://example.com/submodels/nameplate");

To expose the registry in a manually configured server, add the registry node manager factory to the server's node manager factories:

var registry = new Opc.Ua.Aas.Server.Registry.AasRegistryService();
server.NodeManagerFactories.Add(
    new Opc.Ua.Aas.Server.Registry.AasRegistryNodeManagerFactory(registry));

The V3 AAS registry projection uses the shared XRegistryProjectionEngine from Opc.Ua.XRegistry.Server, so base xRegistry lifecycle, labels and file-transfer semantics match the WoT registry implementation.

Registry client

AasRegistryClient derives from XRegistryClient. It resolves the well-known root, inherits the base xRegistry lifecycle helpers, and adds the AAS discovery methods and typed resource clients:

Opc.Ua.Aas.Client.Registry.AasRegistryClient registry =
    await Opc.Ua.Aas.Client.Registry.AasRegistryClient.ForServerAsync(
        session,
        telemetry,
        ct);

ArrayOf<NodeId> shells = await registry.LookupShellsByAssetLinkAsync(
    "serial",
    "42",
    ct);

Opc.Ua.Aas.Client.Registry.AasGetSubmodelDocumentResult submodel = await registry.GetSubmodelAsync(
    "https://example.com/submodels/nameplate",
    ct);

if (StatusCode.IsGood(submodel.StatusCode))
{
    File.WriteAllBytes("nameplate.json", submodel.Document.ToArray());
}

The DI shortcut is AddAasV3RegistryClient:

services
    .AddOpcUa()
    .AddClient(options => { /* endpoint and application options */ })
    .AddAasV3RegistryClient();

---

7. V3 updateable registry and environment export

AasMaterializationCoordinator implements the optional updateable-registry profile of clause 6.5.9. It reads AasMaterializationDocument entries from an IAasMaterializationDocumentStore, prepares shadow generations, atomically switches them through an IAasEnvironmentProjectionHost, records per-document outcomes and skips unchanged digests unless Force is set.

Important behaviours:

• Documents are canonical. Materialized nodes can be rebuilt from the stored documents and the specification. No extra per-node state is required.
• Switches are atomic. Shadow generations are not browsable and do not emit model-change events until committed.
• Failures retain the previous generation. Invalid desired versions stay in the registry with diagnostics while the previous active generation continues serving.
• Graceful retirement is the default. Existing monitored items survive an update until retained work drains; Immediate invalidates affected monitored items with BadNodeIdUnknown.
• Value write-back bumps versions. Writes through materialized nodes update the stored document and avoid redundant projection when the digest is unchanged.

AasEnvironmentExporter implements clause 6.5.10. It exports the whole materialized environment as AAS JSON, XML or AASX and filters the result per the calling session's read access. A filtered export does not publish a digest, because the bytes depend on the caller.

---

8. V3 federation, packages, DPP and WoT

Federation

AAS federation follows clause 6.5.6. AasFederationIdentity derives proxy identity from the remote AAS identifier attributes, never from the local endpoint. AasResourceUrlFederationResolver and AasOpcUaFederationResolver apply a fail-closed egress policy: host/scheme controls, DNS and connected-address checks, redirect/time/size bounds, no ambient credentials and OPC UA peer identity validation.

Packages

AasPackageIntegrity and IAasPackageStore implement the package integrity rules in clause 6.5.4. Package versions publish immutable Digest and DigestAlg; consumers verify the returned blob by default. OCI-backed packages verify the manifest digest, require exactly one package layer descriptor, keep mutable tags separate from immutable VersionIds and keep referrers out of the package version collection.

Digital Product Passport vocabulary

The Dpp/ namespace provides a small Digital Product Passport vocabulary layer. AasDppDisclosurePolicy maps DPP regulatory classes to the AAS Public and Controlled disclosure tiers, while preserving the finer disclosure class and authorization text for consumers.

WoT bridge

Opc.Ua.Aas.WoT implements the informative Annex F projection. AasWotBridge reads a bundle of Thing Descriptions carrying the AAS and OPC UA WoT Binding terms, resolves the type binding (@type, ua:HasTypeDefinition or both), and projects the object graph described by Annex F. It does not replace the WoT Connectivity registry; it is the AAS-specific bridge between the two companion specifications.

---

9. Security and disclosure notes

Registry writes and file updates inherit the xRegistry security model. The AAS GetSubmodel convenience method deliberately re-checks authorization on the target resource; permission to call the method is never substituted for permission to read the file. Denied responses return no bytes, no parse metadata and no size or digest. Concealed targets and nonexistent targets follow the same externally visible branch.

DisclosureTier and Authorization are metadata, not credentials. The implemented DPP policy maps regulatory classes to public or controlled tiers, and tests assert that AASAuthorizationOptionDataType carries configuration only, not passwords, tokens, keys or secrets.

Federation resolves untrusted metadata and therefore fails closed. A resolver policy, DNS, redirect, credential, certificate, identity or resource-bound failure terminates resolution without returning or caching bytes from the rejected destination.

---

10. V3 conformance matrix

The following table maps the sixteen V3 draft clause 10 conformance units to tests in tests/Opc.Ua.Aas.Tests. Each cited test was checked against the behaviour it asserts; no unit is intentionally left unmapped.

A Server publishes the units it actually enables. Both NodeManagers implement IConformanceContributor, and the server aggregates their contributions into Server/ServerCapabilities/ConformanceUnits, so the published set follows what was wired up rather than what the assemblies could in principle do: AAS-OperationInvoke appears only when an operation handler other than DefaultAasOperationHandler is configured, and AAS-Packages (with AAS-PackageIntegrity, which clause 10 requires alongside it) only when a package group is present. The unit names are held in AasConformanceUnits.

ServerProfileArray gains no AAS entry. Clause 10 names conformance units but assigns no server profile URIs, and the IDTA profile identifier of Annex G is qualified on also implementing the HTTP binding, which this stack does not — so publishing it would claim conformance that is not met.

Conformance unit	Demonstrating tests
AAS-Metamodel	Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsAnnexBMembers; Client.AasClientTests.OpenMethodsResolveByIdentifierAndIdShortPath
AAS-SubmodelElements	Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsAnnexBMembers; Serialization.AasSerializationTests.JsonRoundTripPreservesEverySubmodelElementType
AAS-ValueFidelity	Values.AasXsdTypeMapTests.EveryDeclaredXsdTypeIsAssignedADataType; Values.AasXsdTypeMapTests.NoDataTypeIsAssignedToTwoXsdTypes; Values.AasLexicalCanonicalizerTests.CanonicalizationIsIdempotent; Client.AasClientTests.ReadAndWriteValueUseDeclaredXsdType
AAS-InstanceMaterialization	Materialization.AasEnvironmentMaterializerTests.OrderedListUsesHasOrderedComponentAndUnorderedListUsesHasComponent; Materialization.AasEnvironmentMaterializerTests.ListMembersAreNamedByIndexAndCarrySequentialIndex; Materialization.AasEnvironmentMaterializerTests.MaterializingTheSameEnvironmentTwiceProducesByteIdenticalNodeSet
AAS-LosslessRoundTrip	Materialization.AasEnvironmentRoundTripTests.MaterializeThenSerializeProducesEquivalentEnvironment; Materialization.AasEnvironmentRoundTripTests.SerializeThenMaterializeProducesEquivalentNodeSet; Materialization.AasEnvironmentRoundTripTests.ConflatingAbsentWithEmptyIsReported; Materialization.AasEnvironmentRoundTripTests.RewritingValueIntoCanonicalLexicalFormIsNotReported
AAS-Registry	Registry.AasRegistryProjectionTests.ProjectionExposesEverySourceIdentityVerbatim; Registry.AasRegistryProjectionTests.ConcreteRegistryMethodsCarryDeclarationIds; Registry.AasRegistryServiceTests.UpsertResourceAdvancesGenerationAndPreservesExistingSnapshots
AAS-RegistryIdentity	Registry.AasRegistryServiceTests.IdentifierConstructionMatchesXRegistryAndIsInvariantAcrossVersions; Registry.AasRegistryProjectionTests.ProjectionExposesEverySourceIdentityVerbatim; Client.AasRegistryClientTests.TypedGroupAndResourceClientsExposeSourceIdentities
AAS-RegistryVersioning	Registry.AasRegistryServiceTests.VersionOrderingResolvesNewestVersionNotLaterThanMoment; Client.AasRegistryClientTests.VersionsResolveNewestVersionNotLaterThanMoment
AAS-Discovery	Registry.AasRegistryServiceTests.LookupShellsByAssetLinkFindsShellAndBoundsUnauthenticatedResults; Registry.AasRegistryGetSubmodelContractTests.AuthorizedCallerGetsDocumentFormatAndContentType; Client.AasRegistryClientTests.LookupShellsByAssetLinkReturnsHitAndMiss; Client.AasRegistryClientTests.GetSubmodelReturnsDocumentOnSuccess
AAS-OperationInvoke (partial, see section 11)	Server.AasRuntimeInvocationTests.InvokeWithCorrectArityReturnsOperationOutputsAsync; Server.AasRuntimeInvocationTests.InvokeWithArityMismatchReturnsBadInvalidArgumentAsync; Server.AasRuntimeInvocationTests.InvokeOperationFailureReturnsGoodCallStatusAndFalseSuccessAsync; Client.AasClientTests.InvokeMarshalsArguments
AAS-Federation	Federation.AasFederationTests.ProxyIdentityRetainsRemoteAttributesAndIgnoresLocalEndpoint; Federation.AasFederationTests.EgressPolicyRejectsRestrictedAddressAndReturnsNoBytes; Federation.AasFederationTests.ConnectedAddressRevalidationBlocksDnsRebinding; Federation.AasFederationTests.OpcUaPeerIdentityMismatchTerminatesWithoutRemoteRead
AAS-DisclosureTiers	Registry.AasRegistryServiceTests.DisclosureTierAndAuthorizationAdvertiseConfigurationOnly; Registry.AasRegistryServiceTests.ControlledDisclosureTierRequiresAuthenticationButPublicDoesNot; Registry.AasRegistryGetSubmodelContractTests.TargetRolePermissionsDenialReturnsUserAccessDenied; Dpp.AasDppDisclosurePolicyTests.RegulatoryClassesMapToDisclosureTiers
AAS-UpdateableRegistry	Updateable.AasUpdateableRegistryMaterializationTests.ShadowGenerationStaysInvisibleUntilAtomicSwitch; Updateable.AasUpdateableRegistryMaterializationTests.GracefulRetirementServesExistingMonitoredItemUntilDrain; Updateable.AasUpdateableRegistryMaterializationTests.ValidationFailureKeepsPreviousGenerationAndDivergesVersions; Updateable.AasUpdateableRegistryMaterializationTests.ValueWriteBackBumpsVersionWithoutRedundantMaterialization
AAS-EnvironmentExport	Updateable.AasUpdateableRegistryMaterializationTests.EnvironmentExportIsFilteredPerSessionWithNoDigest; Serialization.AasxPackageTests.JsonPackageRoundTripsEnvironmentAndSupplementaryFiles; Serialization.AasxPackageTests.XmlPackageReadsEnvironment
AAS-Packages	Packaging.AasPackageIntegrityTests.PublishedVersionExposesImmutableDigestAndDigestAlg; Packaging.AasPackageIntegrityTests.MovingTagToNewManifestRetainsDistinctVersions; Packaging.AasPackageIntegrityTests.ReferrerDoesNotMutatePackageVersionCollectionOrLifecycle; Client.AasRegistryClientTests.PackageDownloadVerifiesDigestByDefault
AAS-PackageIntegrity	Packaging.AasPackageIntegrityTests.DigestAlgorithmsAcceptOnlyExactAasSpellings; Packaging.AasPackageIntegrityTests.MismatchedBlobIsRejectedBeforeItIsReadable; Packaging.AasPackageIntegrityTests.ConsumerSideVerificationCatchesTamperedBlob; Packaging.AasPackageIntegrityTests.OciBindingPublishesManifestDigestWithPrefixAndDigestWithoutPrefix; Packaging.AasPackageIntegrityTests.OciManifestRequiresExactlyOnePackageLayerDescriptor; Client.AasRegistryClientTests.PackageDownloadRejectsTamperedBlob

---

11. V3 limitations and migration notes

• Annex G / IDTA-01002 Part 2 HTTP APIs are not implemented by this branch.
• Calling a V3 Operation with arguments is incomplete. A materialized Operation carries its Invoke Method, and a Client resolves it by either its own NodeId or the MethodDeclarationId of AASOperationType.Invoke. The Method also carries InputArguments and OutputArguments under the standard BrowseNames. What does not yet work is the Call itself: NodeState.AddChild does not route through MethodState.FindChild, so a Method imported from a NodeSet leaves the typed InputArguments property null, and the Server answers BadTooManyArguments. Closing this needs a change to how the shared NodeSet import claims typed children, which affects every consumer of runtime NodeSets and is therefore out of scope here. samples/Aas exercises the path and reports the status rather than working around it. This limitation is V3-specific; the V2 Operation Method has no declared arguments and is called with an empty input list.
• The AAS registry server currently exposes direct construction through AasRegistryService and AasRegistryNodeManagerFactory; the client has a DI helper (AddAasV3RegistryClient), while the metamodel server has AddAasV3Server.
• This branch adds new AAS packages and the OPC UA Decimal DataType. No manual migration from 1.5.378 is required solely to consume the new AAS libraries; the general 2.0 migration guidance remains in Migration Guide.

---

12. OPC 30270 / AAS V2 half

The OPC 30270 half implements the published "OPC UA for Asset Administration Shell" companion specification for the AAS V2.0.1 metamodel. The static model is generated into Opc.Ua.Aas.V2, its namespace URI is http://opcfoundation.org/UA/I4AAS/, and predefined nodes are loaded with the generated AddOpcUaAasV2 extension. The server and client entry points are AddAasV2Server and AddAasV2Client.

V2 is ingestion-only. Opc.Ua.Aas.V2.AasJsonReader, Opc.Ua.Aas.V2.AasXmlReader and Opc.Ua.Aas.V2.AasxPackageReader parse AAS V2.0.1 documents and AASX packages into the V2 object model; there is no AddressSpace-to-document serializer and therefore no round-trip guarantee. The materializer projects the document into an OPC UA NodeSet:

await using FileStream input = File.OpenRead("environment.json");
Opc.Ua.Aas.V2.AasDocumentReadResult read = await new Opc.Ua.Aas.V2.AasJsonReader()
    .ReadAsync(input, ct);

if (!read.Succeeded)
{
    Console.WriteLine(read.Error);
    return;
}

Opc.Ua.Aas.AasMaterializationResult materialized = Opc.Ua.Aas.V2.AasEnvironmentMaterializer
    .Materialize(read.Environment!);

AddAasV2Server registers the V2 environment NodeManager, the document-backed value provider and the shared operation handler contract:

services
    .AddOpcUa()
    .AddServer(options =>
    {
        options.EndpointUrls.Add("opc.tcp://localhost:4840/AasV2Server");
    })
    .Services
    .AddOpcUa()
    .AddAasV2Server(options =>
    {
        options.ControlNamespaceUri = "urn:example:aas-v2:instances";
    })
    .AddEnvironmentProvider<MyAasV2EnvironmentProvider>()
    .AddOperationHandler<MyAasOperationHandler>();

The runtime surface is Read + Write + Call, matching the rest of this stack. A V2 write reaches IAasValueProvider.WriteValueAsync and stops there: there is no V2 document writer that could persist the change back to JSON, XML or AASX. Operation is an OptionalPlaceholder Method named Operation with no declared arguments, unlike the V3 mandatory Invoke Method, so a V2 Call is zero-argument.

File and Blob content on V2 is served through an embedded standard OPC UA FileType object. Clients call Open, Read and Close on that child rather than reading a V3-style value projection:

var client = new Opc.Ua.Aas.Client.V2.AasClient(session, aasNamespaceIndex, telemetry);
Opc.Ua.Aas.V2.AASFileTypeClient manual = client.OpenFile(
    "https://example.com/submodels/nameplate",
    "Manual");
ByteString content = await client.ReadFileContentAsync(manual.ObjectId, ct: ct);

OPC 30270 leaves instance NodeIds server-specific and defines no addressing convention. The V2 materializer and client deliberately reuse the deterministic AasNodeIdEncoding and AasIdShortPath rules used by the V3 draft, so one addressing scheme serves both generations and neither client has to browse for known identifiers:

var client = new Opc.Ua.Aas.Client.V2.AasClient(session, aasNamespaceIndex, telemetry);
Opc.Ua.Aas.V2.AASPropertyTypeClient temperature = client.OpenProperty(
    "https://example.com/submodels/process",
    "Temperature");

Opc.Ua.Aas.Client.V2.AasValueReadResult current = await client.ReadValueAsync(
    temperature.ObjectId,
    ct);

StatusCode status = await client.WriteValueAsync(
    temperature.ObjectId,
    Opc.Ua.Aas.V2.AASValueTypeDataType.Double,
    new Variant(42.5),
    ct);

V2 has no registry, no packages, no federation and no DPP. Those are V3 draft additions, and the V2 implementation intentionally stops at the OPC 30270 metamodel.

OPC 30270 conformance units

The V2 server publishes the seventeen conformance units from OPC 30270 Table 83 through Server/ServerCapabilities/ConformanceUnits and publishes no ServerProfileArray entry, because Table 84, which would assign profile URIs, is empty. Two internal specification contradictions are resolved in src/Opc.Ua.Aas.Server/V2/AasV2ConformanceUnits.cs: Table 83 misspells the multi-language unit as I4AAS MultiLangaugeProperty while Table 85 spells it I4AAS MultiLanguageProperty, and Table 85 lists an I4AAS Security unit that Table 83 never defines. The implementation publishes the corrected I4AAS MultiLanguageProperty spelling and does not publish I4AAS Security.

Each mapping below was checked against the cited test in tests/Opc.Ua.Aas.Tests/V2/. No OPC 30270 Table 83 unit is currently unmapped.

OPC 30270 Table 83 unit	Demonstrating tests
I4AAS AAS	Model.AasV2ObjectModelTests.ConstructionRetainsV2TopLevelIdentifiablesAndReferences; Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Server.AasV2ServerTests.ConformanceUnitsPublishOpc30270FacetWithoutProfileUris
I4AAS Asset	Model.AasV2ObjectModelTests.ConstructionRetainsV2TopLevelIdentifiablesAndReferences; Model.AasV2ObjectModelTests.V2OnlyConceptsRoundTripThroughModel; Client.AasClientTests.OpenMethodsResolveByIdentifierAndIdShortPath
I4AAS Submodel	Model.AasV2ObjectModelTests.ConstructionRetainsV2TopLevelIdentifiablesAndReferences; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers; Client.AasClientTests.OpenMethodsResolveByIdentifierAndIdShortPath
I4AAS ConceptDescription	Model.AasV2ObjectModelTests.ConceptDescriptionFlavoursRetainIdentifierKinds; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType
I4AAS View	Model.AasV2ObjectModelTests.V2OnlyConceptsRoundTripThroughModel; Materialization.AasEnvironmentMaterializerTests.ShellMaterializesAssetViewsInterfacesAndAasReferences
I4AAS RelationshipElement	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS Property	Model.AasV2ObjectModelTests.SubmodelElementMembersRetainNodeSetTypes; Client.AasClientTests.ReadAndWriteValueUseDeclaredAasValueTypeAsync; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS MultiLanguageProperty	Model.AasV2ObjectModelTests.SubmodelElementMembersRetainNodeSetTypes; Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS Range	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS Blob	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers; Client.AasClientTests.FileAndBlobContentAreReadThroughEmbeddedFileTypeAsync
I4AAS File	Serialization.AasV2SerializationTests.AasxReaderReadsXmlJsonAndSupplementaryFiles; Server.AasV2ServerTests.EmbeddedFileOpenReadAndCloseServeBlobContentAsync; Client.AasClientTests.FileAndBlobContentAreReadThroughEmbeddedFileTypeAsync
I4AAS ReferenceElement	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS Capability	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS SubmodelElementCollection	Model.AasV2ObjectModelTests.V2OnlyConceptsRoundTripThroughModel; Materialization.AasEnvironmentMaterializerTests.OrderedCollectionUsesHasOrderedComponentAndUnorderedCollectionUsesHasComponent; AasV2ModelTests.OrderedCollectionRedeclaresTheSubmodelElementPlaceholder
I4AAS Operation	Materialization.AasEnvironmentMaterializerTests.MaterializedNodeSetImportsIntoAnAddressSpace; Server.AasV2ServerTests.OperationMethodInvokesHandlerAndRejectsArgumentsAsync; Client.AasClientTests.InvokeCallsTheEmbeddedOperationMethodAsync
I4AAS Event	Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Serialization.AasV2SerializationTests.XmlReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers
I4AAS Entity	Model.AasV2ObjectModelTests.SubmodelElementMembersRetainNodeSetTypes; Serialization.AasV2SerializationTests.JsonReaderParsesV2EnvironmentAndEverySubmodelElementType; Materialization.AasEnvironmentMaterializerTests.EverySubmodelElementTypeMaterializesWithItsMembers

---

13. References

• OPC 30270, "OPC UA for Asset Administration Shell", namespace http://opcfoundation.org/UA/I4AAS/.
• OPC UA for Asset Administration Shell V3 draft, release 3.00-draft3, namespace http://opcfoundation.org/UA/I4AAS/v3/.
• xRegistry — abstract registry base model.
• OPC UA WoT Connectivity.
• Dependency Injection.
• Runtime NodeSets.