diff --git a/README.md b/README.md index 695085515..2f6111fe5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# This is the repository of the Asset Administration Shell +# IDTA-01001 - Metamodel of the Asset Administration Shell [![Check]( https://github.com/admin-shell-io/aas-specs/workflows/Check/badge.svg @@ -11,7 +11,13 @@ https://licensebuttons.net/l/by/4.0/88x31.png https://creativecommons.org/licenses/by/4.0/ ) -This repository contains specifications of the Asset Administration Shell, including the normative schemas of the serializations, the rules applied to create them, how the specification is mapped into the serializations, and examples of how to use the schemas. +This repository contains specifications of the metamodel of the Asset Administration Shell, including the normative schemas of the serializations, the rules applied to create them, how the specification is mapped into the serializations, and examples of how to use the schemas. + +## Industrial Digital Twin Association (IDTA) + +Governance of the specification is done in the working group Open Technology of the [IDTA](https://industrialdigitaltwin.org/en/) + +The specification number is: **IDTA-01001** ## Industrial Digital Twin Association (IDTA) @@ -66,7 +72,7 @@ Previous releases (deprecated by [3.0.7](https://github.com/admin-shell-io/aas-s Feature requests, reports about inconsistencies, mistakes *etc.* are highly welcome! Please [submit a new issue]( -https://github.com/admin-shell-io/aas-specs/issues/new +https://github.com/admin-shell-io/aas-specs/issues/new/choose ). If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/documentation/IDTA-01001/antora.yml b/documentation/IDTA-01001/antora.yml new file mode 100644 index 000000000..d0202ae22 --- /dev/null +++ b/documentation/IDTA-01001/antora.yml @@ -0,0 +1,6 @@ +name: IDTA-01001 +title: Specification Asset Administration Shell - Part 1 Metamodel +version: 'snapshot' +start_page: ROOT:index.adoc +nav: + - modules/ROOT/nav.adoc \ No newline at end of file diff --git a/documentation/IDTA-01001/idta-logo.png b/documentation/IDTA-01001/idta-logo.png new file mode 100644 index 000000000..b3d6c42ba Binary files /dev/null and b/documentation/IDTA-01001/idta-logo.png differ diff --git a/documentation/IDTA-01001/modules/ROOT/Annex/IDTA-01001_ChangeLog.adoc b/documentation/IDTA-01001/modules/ROOT/Annex/IDTA-01001_ChangeLog.adoc new file mode 100644 index 000000000..4683e746a --- /dev/null +++ b/documentation/IDTA-01001/modules/ROOT/Annex/IDTA-01001_ChangeLog.adoc @@ -0,0 +1,1990 @@ +//// +Copyright (c) 2023 Industrial Digital Twin Association + +This work is licensed under a [Creative Commons Attribution 4.0 International License]( +https://creativecommons.org/licenses/by/4.0/). + +SPDX-License-Identifier: CC-BY-4.0 + +Illustrations: +Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, designed by Publik. Agentur für Kommunikation GmbH +//// + +[appendix] + +== Metamodel Changes + +=== General + +This annex lists the changes from version to version of the metamodel, together with major changes in the overall document. Non-backward compatible changes (nc) are marked as such. + +nc="x" means non-backward compatible; if no value is added in the table, then the change is backward compatible. + +nc="(x)" means that the change made was implicitly contained or stated in the document before and is now being formalized. Therefore, the change is considered to be backward compatible. + +Before splitting the document, changes to the data specification templates and the security of the metamodel were listed in separate tables. + +Three tables are introduced to explain the changes: + +. changes w.r.t. previous version, +. new elements in metamodel w.r.t previous version, +. new, changed, or removed constraints w.r.t previous version. + +If there are no changes the corresponding tables are obmitted. + + +==== +Note: before V3.0, the security metamodel and the predefined data specifications were also part of this document. Therefore, security metamodel changes were listed using the three subclauses as described above. +==== + + +=== Changes V3.1 vs. V3.0 + +Major Changes: + +* New value "Role" to enumeration AssetKind [#294](https://github.com/admin-shell-io/aas-specs/issues/294) +* PathType: support complete URI scheme for files RFC3986/RFC3987 [#299](https://github.com/admin-shell-io/aas-specs/issues/299) +* data type Identifier: change length from 2000 to 2024 characters [#306](https://github.com/admin-shell-io/aas-specs/issues/306) +* Referable/idShort and Constraint AASd-002: now also allows hyphens to be included in name [#295](https://github.com/admin-shell-io/aas-specs/issues/295) +* Entity/entityType and Constraint AASd-014: now optional [#287](https://github.com/admin-shell-io/aas-specs/issues/287) + + +Minor Changes: + +* editorial changes + + +Bugfixes: + +* (Editorial) MultiLanguageNameType inconsistent description, maxLength=128 (schemata were correct) ([#313](https://github.com/admin-shell-io/aas-specs/issues/313)) +* (Editorial) HasKind/kind explanataroy text: use template, not type ([#313](https://github.com/admin-shell-io/aas-specs/issues/313)) +* (Editorial) DataTypeDefXsd links now correctly to xmlschema11-2, not to xsd V1.1 ([#312](https://github.com/admin-shell-io/aas-specs/issues/312) (as implemented in schemata) +* (Editorial) make mbeddedDataSpecification/dataSpecification mandatory (as implemented in schemata) [#296](https://github.com/admin-shell-io/aas-specs/issues/296) + + +.Changes +[cols="5%,42%,48%",options="header",] +|=== +|*Nc* |*V3.0 Change w.r.t. V2.0.1* |*Comment* +| | AssetKind | Add new value "Role" to enumeration AssetKind +| | DataTypeDefXsd | (bugfix in Text only) values in enumeration now reference xsd V1.0, not V1.1 +| | EmbeddedDataSpecification/dataSpecification | (bugfix in Text only) now mandatory +| | Entity/entityType | now optional +| | Identifier | change length from 2000 to 2024 characters +| | MultiLanguageNameType | (bugfix in Text only) maxLength=128 (as derived and implemented) +| | NameType | change due to change of Constraint AASd-002 +| | PathType | extend data type to support complete URI scheme for files RFC3986/RFC3987 +|=== + +.New Elements in Metamodel +[cols="5%,41%,51%",options="header",] +|=== +| |*New Elements V3.0 vs V2.0.1* |*Comment* +|| AssetKind/Role | New value in enumeration +|=== + + +.New, Changed or Removed Constraints +[cols="5%,10%,15%,69%",options="header",] +|=== +|*Nc* |*V3.0 vs. V2.0.1* |*New, Update, Removed, Reformulated* |*Comment* +| |AASd-002 |Update a| +now also allows hyphens to be included in name + +Constraint AASd-002: _idShort_ of __Referable__s shall only feature letters, digits, hyphen ("-") and underscore ("_"); starting mandatory with a letter, and not ending with a hypen or underscore, i.e. ^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$.]. +| | AASd-014 | Update a| +Change since Entity/entityType is now optional + +Constraint AASd-014: Either the attribute globalAssetId or specificAssetId of an Entity must be set if Entity/entityType is set to "SelfManagedEntity". +|=== + + +=== Changes V3.0 vs. V2.0.1 + +Major Changes: + +* Document split into several documents: Part 1 on metamodel of the AAS (this document), Part 5 on the aasx package exchange format, Part 3 series on the predefined data specifications, and Part 4 (security) +* CHANGED: Split of SubmodelElementCollection into SubmodelElementList (with orderRelevant) and SubmodelElementCollection +* CHANGED: Reference type and referredSemanticId added to Reference; Local and Parent attributes removed from Reference. Logical enumeration concept updated. Some renaming and some new enumerations. Constraint added for references. Grammar for text serialization updated. +* CHANGED: idType from Identifier removed, ID now string +* CHANGED: idShort of Referable now optional + Constraints added with respect to ID and idShort, includes that idShort of Submodels etc. no longer need to be unique in the context of an AssetAdministrationShell +* CHANGED: semanticId no longer mandatory but recommended for SubmodelElement. semanticId now recommended not only for submodel instance but also for submodel template +* NEW: supplemental Semantic IDs +* CHANGED: SubmodelElements do no longer inherit from HasKind, only Submodel has distinction between submodel template or submodel instance (including update of tAAS-#18 and -#19) +* CHANGED: Revised concept on handling of Asset and assetIdentificationModel (assetInformation), Asset removed, no Asset/billOfMaterial any longer. Specific asset IDs added. +* CHANGED: Attributes with type "string" were substituted by string types with length restrictions + some more constraints on string handling. LangSringSet handling updated. +* REMOVED: ConceptDictionaries removed, no longer supported +* REMOVED: Views removed, no longer supported +* NEW: Events now experimental parts of normative part (including renaming and smaller changes) +* NEW: Besides type assets and instance assets, assets for which this kind of classification is not applicable are also supported (conformant to IEC 63278-1) +* REMOVED: Security attribute removed from Asset Administration Shell, Access Control remains part of the specification +* ENHANCED: DataTypeIEC61360 extended with values for IRI, IRDI, BLOB, FILE + corresponding new constraints added +* CHANGED: Handling of attributes with xsd-related types like DataTypeDef. New types introduced. +* NEW: hasExtensions introduced +* CHANGED: In some mappings or serializations, the type "Reference" is converted into a single string. In this case, it is now required (and not only recommended) to use the defined string serialization. +* CHANGED: Extracted and not part of this specification any longer; mapping rules for different serializations + Schemata + Example in different serializations +* CHANGED: Referable/category set to \<> +* NEW: Besides \<>, new stereotype \<> introduced +* NEW: Qualifier/kind introduced (ValueQualifier, TemplateQualifier, ConceptQualifier) +* CHANGED: Terms and Definitions updated to be conformant to IEC 63278-1 DRAFT, July 2022 (note: this document contains more terms and definitions than IEC 63278-1 and vice versa: not all terms and definitions from IEC 63278-1 are included). Definition of view removed. Definition of service added from Part 2. +* CHANGED: Description of ModellingKind +* Parent attribute in Referables removed +* NEW: Two new terms introduced: coded value and explicit value +* CHANGED: Updated grammar on how to define semantic identifiers for metamodel elements of this specification +* CHANGED: Blob type changed from byte[0..*] to base64Binary +* NEW: Appendix for Backus-Naur form (BNF) + update of all grammars using BNF and variants so that they are using consistent grammar language +* NEW: Clause on embedded data specifications +* EDITORIAL: Text updated, no kind column any longer in class tables, instead notation of ModelReference<\{Referable}>. New table for Primitives/Data Types +* EDITORIAL: New clause "Introduction" +* EDITORIAL: New clause "Matching strategies for semantic identifiers" +* EDITORIAL (REMOVED): Clause on Tooling and Open Source removed +* EDITORIAL: Vector graphics +* NEW: Constraints implicitly contained in text were formalized and numbered (normative) +* NEW: Environment explicitly part of UML (was part of serializations from the beginning) + +Bugfixes: + +* Corrected Japanese example for xd:string +* HasDataSpecification/embeddedDataSpecs 0..* not 0..1 +* Qualifer is and never was abstract (Constraint was), table was correct, UML corrected +* Correct AASd-051: VIEW no longer supported +* Type of SubmodelElementList/typeValueListElement corrected to AasSubmodelElements (before SubmodelElementElements + +* Missing table for enumeration ReferenceTypes added +* Bugfix table specifications w.r.t. kind of attribute (from aggr to attr – column kind was removed, see above) + +Smaller changes: + +* EDITORIAL: Qualifier description updated +* EDITORIAL: Reformulation of constraints dealing with References and Key/type +* EDITORIAL: Examples now with https: and not http: +* EDITORIAL: Footnotes reused +* EDITORIAL: Added explanation for annotated relationship elements +* EDITORIAL: Asset type and asset instance now type asset and instance asset (conformant to IEC 63278-1) +* EDITORIAL: example for langString serialization changed (table 6) + +==== Metamodel Changes V3.0 vs. V2.0.1 + +.Changes +[cols="5%,42%,48%",options="header",] +|=== +|*Nc* |*V3.0 Change w.r.t. V2.0.1* |*Comment* +| |anySimpleTypeDef |Type removed, was no longer used in any class definition, was mentioned in text only. +|X |Asset |Removed, asset referenced via AssetInformation/globalAssetId only +|X |AssetAdministrationShell/asset |Removed, substituted by AssetAdministrationShell/assetInformation (but no reference any longer, instead now aggregation) +|X |AssetAdministrationShell/conceptDictionaries |Removed +|X |AssetAdministrationShell/security a| + +Removed + +==== +Note: Security is still part of the Asset Administration Shell, but the Asset Administration Shell and its elements are referenced from Security. +==== + +| x |AssetAdministrationShell/view |Removed, Views no longer supported +|  |AssetKind/Instance |Updated description of value "Instance" of enumeration "AssetKind" conformant to IEC 63278-1 +|  |AssetKind/Type |Updated description of value "Type" of enumeration "AssetKind" conformant to IEC 63278-1 +|X |BasicEvent |Renamed to BasicEventElement and set to \<> +|file:///C:/__localWork/Asset%20Administration%20Shell%20-%20Verwaltungsschale/Verwaltungsschale%20im%20Detail%20-%20part%201a%20V3.0/Change%202.0%20-%203.0.xlsx#RANGE!#REF![(x)link:#bib2[[2\]]] |xref:BlobType[BlobType |Primitive changed from "group of bytes" to Base64Binary +|X |ConceptDictionary |Removed +|X |Constraint |Abstract class removed. Formula now used in Security part only +|x  |xref:DataSpecification[DataSpecification] |No longer inherits from Identifiable. However, same attribute names and types +|x |DataSpecification/description |Type changed from LangStringSet to MultiLanguageTextType, thus adding a length constraint +| |xref:DataSpecificationContent[DataSpecificationContent] |Stereotype \<