Page Comparison

#04 20170830

Arne,

Da Ehsan allerede har ”laget” et extension schema (EXPRESS_EXTENSION_SCHEMA AP239_ARM_LF_EPM_EXTENSION FOR AP239_PRODUCT_LIFE_CYCLE_SUPPORT_ARM_LF;) og Ernest skal gå igang med å lage et IFC4 extension schema for WorkOrder(?), er det viktig at vi fryser ”syntax og funksjonalitet” asap. Så fint med din tilbakemelding så snart som mulig.

EXPRESS_EXTENSION_SCHEMA Declaration

EXPRESS_EXTENSION_SCHEMA   extensionSchemaName FOR expressSchemaName; <body>  END_EXPRESS_EXTENSION_SCHEMA;

EXPRESS_EXTENSION_SCHEMA   extensionSchemaName {‘GUID’} FOR expressSchemaName;<body>  END_EXPRESS_EXTENSION_SCHEMA;

The reason for the optional GUID is to be able to track/label one particular version of an extension schema and population(data).

Example: exporting a population including “extension schema data” on a step file package. When importing such step file package, the GUID is used to ensure that the extension schemata in the importing DB is exactly the same as in the exporting DB. There will be an option in write/read step file package to include exporting/defining of the extension schemata.

ENTITY Declaration

ENTITY declarations in an extension schema have the same syntax as in an Express schema except the following:

Declarations not supported: UNIQUE , WHERE
Extension: GENERIC_ENTITY is allowed as domain for all attribute types.
Extension: INVERSE attribute may be declared: ALL_LOCAL_REFS_TO_ME : SET OF GENERIC_ENTITY; -- no “ FOR ‘attributeName’ “
- The attribute will return a set containing all instances that refers this instance within the same model
Extension: INVERSE attribute may be declared: ALL_CROSS_MODEL_REFS_TO_ME : SET OF GENERIC_ENTITY; -- no “ FOR ‘attributeName’ “
- The attribute will return a set containing all instances that refers this instance within the same database - all models

Code Block

title	Example
collapse	true

-- extend the IFC schema with a window suitable for cars	
ENTITY xifcWindShield SUBTYPE of IfcWindow;		
	fitsMakes : LIST OF xifcVehicle; -- list of car makes that this window will fit in
END_ENTITY;
 
ENTITY xifcVehicle;		
	brand : STRING; 	-- i.e. 'Ford'		
	model : STRING;  	-- i-e 'T'        
	year  : STRING; 	-- i.e '1921-1924'    
END_ENTITY;

ENTITY_EXTENSION Declaration

The ENTITY_EXTENSION – END_ENTITY_EXTENSION as earlier agreed, plus the same extensions for attribute declarations as for ENTITY.

ENTITY_EXTENSION ‘entity_extension_name’ FOR ‘expressEntityName’; <body>  END_ENTITY_EXTENSION;

ENTITY_EXTENSION ‘entity_extension_name’ FOR SUBTYPES ‘expressEntityName’; <body>  END_ENTITY_EXTENSION;

Additional rules:

EESR #22: A name of an ENTITY_ EXTENSION declaration must only be unique in the collection of all ENTITY_EXTENSION declarations in the actual extension schema. (22)
- Technically there is no problem to allow an ENTITY_EXTENSION name to have the same name as other declarations (ENTITY, TYPE, FUNCTION …etc), but for “readability” we may not permit it.

EESR #23: There must be only one ENTITY_ EXTENSION declaration for the same entity in one extension schema

With the use of SUBTYPES declaration, there may be implicitly more than one ENTITY_ EXTENSION that extends the same entity:

Expand

title	Example

Example:

     ENTITY_EXTENSION Extend_ifcWindow  FOR ifcWindow;

          ……

     END_ ENTITY_EXTENSION;

     ENTITY_EXTENSION Extend_ifcRoot FOR SUBTYPES ifcRoot;

              ……

     END_ ENTITY_EXTENSION;

In this example, both the Extend_ifcWindow (explicitly) and Extend_ifcRoot (implicitly) will extend the ifcWindow entity.

We can discuss how many of the ”extension schema rules checking” we implement in the compiler and how many we implement in the edmCloseExtensionSchemaCompilerModel() (similar as edmCloseCompilerModel()).

Supported EXPRESS Declarations

The following Express declarations are supported:

TYPE - without the WHERE
ENTITY – with the above listed restrictions and extensions
Subtype_constraint – to be decided???
CONSTANT
FUNCTION
PROCEDURE

Not supported EXPRESS Declarations

The following Express declarations are not supported:

SCHEMA
RULE (Rules can be written in separate RULE_SCHEMA)

New tokens (reserved words):

         ALL_CROSS_MODEL_REFS_TO_ME
         ALL_LOCAL_REFS_TO_ME
         END_ENTITY_EXTENSION
         ENTITY_EXTENSION
         END_EXPRESS_EXTENSION_SCHEMA
         EXPRESS_EXTENSION_SCHEMA
         SUBTYPES

Compiler checking

In addition to the “standard compilation time checking” during defining (compilation) of an extension schema, the following will be checked:

EESR #31: NumberOfExtensionSchema for ExpressSchema < MAX_EXTENSION_SCHEMATA for an Express schema
EESR #32: ExtensionSchema name already exist for the particular Express schema
EESR #33: All ENTITY names must be unique in the collection of Express schema and all extension schemata for the actual Express schema.
EESR #34: In addition to the rule in the Express language for “unique attribute names in an Entity declaration” , attribute names must be unique in the collection of all ENTITY_EXTENSION for a particular entity in all extension schemata for the actual Express schema.
- The ALL_CROSS_MODEL_REFS_TO_ME and ALL_LOCAL_REFS_TO_ME are exceptions to this constraint. When a combination of extension schemata results in more duplicates of these attributes, this “problem” will be resolved when the actual model will be created, such that the actual entity instances will have only one occurrence of each of these attributes;

We can discuss how many of the ”extension schema rules checking” we implement in the compiler and how many we implement in the edmCloseExtensionSchemaCompilerModel() (similar as edmCloseCompilerModel()).

Syntax Illustration 0.3

Code Block

EXPRESS_EXTENSION_SCHEMA   ExtensionSchemaName FOR IFC2X3;

    ENTITY_EXTENSION extToIfcxx1 FOR  ifcxx1;
       (* Attribute name must be unique within the extended entity (ifcxx1), may be same as
          attribute names in super type Entity. When so, this extended attribute must be
          accessed by name using "full qualified attribute name".
          The attribute domains can be any domain in the actual schema or domain (instance type)
          defined in the current extension schema
       *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    DERIVE
		extendedDeriveAttr : SET OF GENERIC_ENTITY := ExtFunc(SELF);
    INVERSE
       ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
	   ALL_LOCAL_REFS_TO_ME : SET OF  GENERIC_ENTITY;             -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_ENTITY_EXTENSION;

    ENTITY_EXTENSION extToifcxx2 FOR SUBTYPES ifcxx2;
       (* same as ENTITY_EXTENSION except that all extensions will be valid for all subtypes of the extended entity, i.e., all subtypes of ifcxx2 *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    INVERSE
       ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
	   ALL_LOCAL_REFS_TO_ME : SET OF  GENERIC_ENTITY;             -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_ENTITY_EXTENSION;
     
    ENTITY_EXTENSION  name; -- no FOR clause means it is a "new" entity
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        -- ........
     INVERSE
        -- .......
        ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
    END_ENTITY_EXTENSION;

    ENTITY_EXTENSION name SUBTYPE OF (FOR entity1, entity2, ... entityN);  -- subtype of any entity in main schema (FOR xxx) or "extended entity" in schema
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        -- ........
     INVERSE
        -- .......
        ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
        ALL_LOCAL_REFS_TO_ME : SET OF  GENERIC_ENTITY;             -- reserved name, keeps all references from other models
    END_ENTITY_EXTENSION;
	

END_EXPRESS_EXTENSION_SCHEMA;

Historical:

...

title	History

Code Block

title	ExtensionSchema 0.1
collapse	true

EXPRESS_EXTENSION_SCHEMA   ExtensionSchemaName FOR IFC2X3;

    EXTEND_ENTITY   ifcxx1;
       (* Attribute name must be unique within the extended entity (ifcxx1), may be same as
          attribute names in super type Entity. When so, this extended attribute must be
          accessed by name using "full qualified attribute name".
          The attribute domains can be any domain in the actual schema or domain (instance type)
          defined in the current extension schema
       *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    INVERSE
       ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_EXTEND_ENTITY;

    EXTEND_ENTITY_AND_SUBTYPES   ifcxx2;
       (* same as EXTEND_ENTITY except that all extensions will be valid for all subtypes of the extended entity, i.e., all subtypes of ifcxx2 *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    INVERSE
       ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_EXTEND_ENTITY;
     
    NEW_EXTENSION_ENTITY name;
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        ........
     INVERSE
        .......
        ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
    END_NEW_EXSENSION_ENTITY;

     NEW_NEW_EXTENSION_ENTITY name SUBTYPE OF (entity1, entity2, ... entityN);  -- subtype of any entity or "extended entity" in schema
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        ........
     INVERSE
        .......
        ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
    END_NEW_EXTENSION_ENTITY;

END_EXPRESS_EXTENSION_SCHEMA;

Arnes adjusted proposal out of Hans Karsten initial spec:

Declarations should be like nouns not verbs
Avoid new keywords, there are too many already. Try reusing existing
Use "FOR" to explicit scope to EXPRESS scema
Entity extensions always have own name
Use leading underscore for "EDM extension" ALL_CROSS_.....

Code Block

title	ExtensionSchema 0.2
collapse	true

EXTENSION_SCHEMA   ExtensionSchemaName FOR IFC2X3;

    ENTITY_EXTENSION extToifcxx1 FOR ifcxx1 ;
       (* Attribute name must be unique within the extended entity (ifcxx1), may be same as
          attribute names in super type Entity. When so, this extended attribute must be
          accessed by name using "full qualified attribute name".
          The attribute domains can be any domain in the actual schema or domain (instance type)
          defined in the current extension schema
       *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    INVERSE
       _ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_ENTITY_EXTENSION;

    ENTITY_EXTENSION extToifcxx2 FOR SUBTYPE(S) ifcxx2;
       (* supplying SUBTYPES enables all extensions will be valid for all subtypes of the extended entity, i.e., all subtypes of ifcxx2 *)
       extendedExplicitAttr1 : STRING;           -- any simple data type can be used, not defined types
       extendedExplicitAttr2 : GENERIC_ENTITY;   --sdaiINSTANCE of any type. can be used as link to instance in any other model.
       extendedExplicitAttr3 : SET OF GENERIC_ENTITY;
    INVERSE
       _ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
       extendedInverseAttr : SET OF GENERIC_ENTITY FOR (entityx.explicitAttr1, entityx.explicitAttr2, ...entityz.explicitAttr5);
    END_ENTITY_EXTENSION;
     
     ENTITY_EXTENSION name; -- lacking FOR part means a new entity
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        ........
     INVERSE
        .......
        _ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
    END_ENTITY_EXTENSION;


     ENTITY_EXTENSION name SUBTYPE OF (FOR entity1, extendedentity2, ... entityN);  -- subtype of any entity (FOR x) or "extended entity" in schema
        explicitAttr1 : INTEGER;
        explicitAttr2 : GENERIC_ENTITY;
        ........
     INVERSE
        .......
        _ALL_CROSS_MODEL_REFERENCES_TO_ME : SET OF GENERIC_ENTITY;  -- reserved name, keeps all references from other models
    END_ENTITY_EXTENSION;

END_EXTENSION_SCHEMA;

...

What is EDM Extension Schema?

The extension schema adds data capabilities to an existing EXPRESS Schema, preserving the original schema so a standard compliant STEP file can still be provided - but of course without the extended data. The extensions are in principle quite simple;

You can extend entities declared in the base schema with new attributes

Code Block
ENTITY_EXTENSION xIfcSpace for IfcSpace; stoId : STRING; --- the global id for any room within STOE enterprise END_ENTITY_EXTENSION;

You can add new entities to the schema, these entities can be new roots or subtypes of the base schema entities.

Code Block
ENTITY xIfcWorkTask SUBTYPE OF(IfcTask); subTaskOf : xIfcWorkTask; dependentOn : SET[0:*] OF xIfcWorkTask; END_ENTITY;

The attributes declared in an EXTENSION_SCHEMA can in addition to the "normal" domains also be of type GENERIC_ENTITY and EDM specific types like _FILE and _DATETIME;
The acronym is "EEX" from EDM EXPRESS Extension Schema, and is also the file extension used for such files.

Current state of the EDM Extension schema

The kernel part is implemented in its first version
The EDMcompiler is enhanced to handle the new schema type, not 100% yet but enough to start testing. Ref JIRA: ECORE-320
Only available as source for self-compiling. Nightly builds will be available estimated 2017.09.20
For current specification see EEX Specification

Using EDM Extension schema

For using extension schema from EDMI see EDMinterface/C API
For using EEX from query schemata see EEX Usage

Q&A:

What is aim to introduce the stuff?

Very short answer: EEX is introduced to add functionality to existing schemata, for example ifc4, to be able to store data not modeled in the original schema. An example could be work_order schema modelled as ifc4 + work_order extension.

We have in EXPRESS interface specifications like USE/REFERENCE, what is difference between interfaces and this extension?

The extensions does not modifiy the orignal schema nor its data, so export/import of IFC4 "part" of the extended model is still posiible. This opposed to USE/REFERENCE FROM which in reality creates a new not compatible schema. SO extensions schema is an "extensions" to the datamodel as rule schema is.

What is difference in handling extension schema comparing to regular Express schemata?

Extensions can only be used for models created "widh 1 to N number of EEX" See functions edmiCreatwModelWithExtensionSchema and xpfCreateModelWithExtensionSchema.

All EDMI functions and XPX functions operating on entities and attributes defined in the actual Express schema can be used to access all entities and attributes defined in the actual set of EEX.

Could be query/rule/map schemata defined against the extension schema?

An EEX cannot be used as a "FOR schema" in the declaration of a QUERY or RULE schema. However, all enties and attributes defined in an EEX can be accessed in a QUERY schema in the same way as entities and attributes defined in the underlying Express schema.

There is currently no plan to imlement any rules or constraint in an EEX, Hence, an EEX will have no influence on any data validation operations

An EEX cannot be used as a SOURCE or TARGET schema in MAP schema. However, all enties and attributes defined in an EEX can be accessed in a MAP schema in the same way as entities and attributes defined in the SOURCE and/or TARGET schema.

Would we have some special syntax support in XPX language to handle extension items?

Apart from the XPX extensions defined in the extension schema itself there are not foreseen any extensions to the language. But some edmi (XPX) functions are added to handle the extension meta-info, see for example edmiGetExtensionSchemaExtendedEntities.

How does it work in import/export?

All STEP write operations will be enhanced with options to include all relevant EEX data and the EEX (schema) in the resulting STEP file. In the same way, all STEP read operations will be enhanced with options to read and define the EEX schema from the STEP file as well as options to read the actual EEX data. All these new options will only be effective when the "STEP_FILE_PACKAGE" option is enabled.

How will be metadata of the extension stored in dictionary model?

The two new declarations EXPRESS_EXTENSION_SCHEMA and EXTENSION_ENTITY defined in the EEX concpt are not modelled in SDAI_DICTIONARY_MODEL Express schema. These two consepts are stored as "structs" in the dictionary model. Hence the database version is not impacted by introducing the EEX concepts.

Except for the above mentioned two new concepts, all other declarations (concepts) in an EEX is stored in the actual dictionary model as instances of entities defined in the SDAI_DICTIONARY_MODEL Express schema. To avoid influencing the instances of the underlying Express schema, these instances are not stored in the "sdai_model.content.instances" aggregate and not in any "Entity_Extent".

However all instances belonging to one EEX will be stored in one aggregate, owned by the EXPRESS_EXTENSION_SCHEMA struct, to enable the deletion of all instances belonging to the actual EEX upon a delete EEX operation.

Whwn creating a data model using 1 to N number of EEX, the actual "entity descriptors" and "attribute descriptors" defined in all used EEX will be stored in the actual data model. Hence, when using EEX, meta data is partly in the actual dictionary model and in the actual data model itself. The meta data in a data model is not stored as instances, but as "persistent structs"

Any difference in data validation against regular models?

Unless explicitly called for, extension should not impact any validation (Arne Tøn thinks). But in the future we may enhance the validation to include the extensions as well.

Note

Comments wanted!

Since we are about to enable EEX in the EDM it is importrant that any missing or non optimal functionality are noted and corrected. Comments can be posted here or sent to Arne T.

Versions Compared

Old Version 11

New Version Current

Key

#04 20170830

EXPRESS_EXTENSION_SCHEMA Declaration

ENTITY Declaration

ENTITY_EXTENSION Declaration

Supported EXPRESS Declarations

Not supported EXPRESS Declarations

New tokens (reserved words):

Compiler checking

Syntax Illustration 0.3

Historical:

What is EDM Extension Schema?

Current state of the EDM Extension schema

Using EDM Extension schema

Q&A:

What is aim to introduce the stuff?

We have in EXPRESS interface specifications like USE/REFERENCE, what is difference between interfaces and this extension?

What is difference in handling extension schema comparing to regular Express schemata?

Could be query/rule/map schemata defined against the extension schema?

Would we have some special syntax support in XPX language to handle extension items?

How does it work in import/export?

How will be metadata of the extension stored in dictionary model?

Any difference in data validation against regular models?

Comments wanted!