gfse / specif Goto Github PK

In the dataTypes section in the schema is a restriction included to have at least 1 item in the array.

I think there are some use cases where no data types are included - if a SpecIF file uses just standardized data types and other metatypes.

So I suggest to remove this constraint from the schema.

In SpecIF-level-3 (master branch), the titles of the values of an enumerated dataType shall be specified in different languages. Then, a viewer can display the enumerated values in the appropriate language.
The specification may be viewed completely language-dependent:

• The viewer (tool) may translate the SpecIF vocabulary terms to the desired language
• The author may provide the values of an enumerated dataType in different languages, the viewer selects the appropriate text value according to the desired language.
• The property text values, equally.

@oalt :
Thanks for your effort to prepare the "semantics" folder. It is a good idea to provide some semantic guidelines: As you do, I believe that an agreed upon vocabulary makes the difference. And then, why not provide ready-to-use SpecIF-templates.

I would like to propose, however, to combine all x01_... files into a single one that is schema-compliant. Anyways, the resourceClasses need the dataTypes ...

In addition we could provide different templates for different purposes. For example we could provide a very simple template with just a resourceClass "requirement" having 4 propertyClasses in addition to the "full-fledged" template you have added. And perhaps somebody else has a different focus and supplies something different from the FMC fundamental model element types we both find useful for model integration. For example I recall a TdSE-2017 conference session by Markus Brandstätter proposing an "Artefaktmodell zur Verbesserung der Prozessmodellierung".

Finally, I propose to create a new file extension for templates, e.g. 'specift' and 'speciftz'. When importing, a new project id could be generated automatically (by convention) to assure that multiple projects based on the same template carry different identifiers.

What do you think?

We should include in the Concepts chapter of the specification a further section describing the approach of semantic model integration using the FMC elements as base.

Currently a 'resource' has an attribute ‚resourceType‘ and a 'statement' has an attribute ‚statementType‘; similarly 'hierarchy' and 'property'. The idea was to express with the attribute-name what it is. While this makes the data easier to read and to understand (who actually wants to do that ;-), it is more difficult to process.
Thus another approach: Anyways, the context defines what a valid value is in each case (a 'resource' needs a ‚resourceType‘ and so on). Thus a constraint check can easily ascertain that a meaningful reference has been made in a particular situation. From a programming point of view a polymorphic approach is by far preferrable: All instances of type 'resource', 'statement', 'hierarchy' and 'property' get a commonly named attribute 'type'. Then a common code can process all instance types without distinguishing the cases.

Opinions?

When merging models from different tools, the same element has different ids with all likelyhood. We should keep track of original ids, which can be used for searching or updating. As there can be more than one original id, it should be a list.

... starting with SpecIF v1.0

Today, a resource or statement instance may have redundant titles as native (top-level) attribute and as an element in the properties list. Similarly for descriptions.

@oalt proposes: Omit native title and description to omit potential redundancy. In future all properties including title and description must be specified as elements in the properties list.

In mechatronic systems (and others), a numeric value is often to be understood as measure of a unit, e.g. [m], [m/s] or [m^3/kg]. We haven't talked about this, yet. Where to specify a unit, dataType or propertyType? Both is basically possible, but if ranges are defined with the dataTypes, units should be as well.
This question will get at us at the latest when we want to transform SysML parametric models.
Opinion, @oalt, @oeichmann and @S-Ruesch ?

@oalt , you have provided a whole bunch of standard types to be used in different domains or for different purposes. Except for the basic ones, the files do not comply with the schema.
When using 'extends' at the project level, we can indicate that together with another more basic file, there is complete and schema-compliant content.

Importing the HSUV Model of 2020-02-20, there are SpecIF:shows statements for Requirements, even though the statementClass does not allow it.

I have made a new logo design for SpecIF based on the colors @odungern had used in his logo design. The idea behind my design is

• The integrating aspect of SpecIF, symbolized by the central green hexagon
• The integrated systems/tools/formats around
• Use a font, that "expresses" the technical character of a file format
  
  @oeichmann @S-Ruesch @odungern What do you think about it? I am not a graphic designer. Perhaps anyone has a better idea...

The used fonts are:

• Rockwell Nova for 'SpecIF'
• Rockwell Nova Light for 'Specification Integration Facility'

In trying mapping some data to SpecIF, I have the problem, that sometimes it would be very helpful, if you could add a Statement, that comes or goes from or to another statement. I provided just one example here:

This diagram expresses, that the two resources and the writes-Statement are shown on the diagram. Currently this is not possible to express. You just can split the Statement between the two resources in two parts and add a "Dummy"-resource in the middle as Object for the shows statement. I think this is not a good solution to solve the problem.
No change at the schema definition is necessary. It is just a semantic change/extension, that a subject- or object-key in a statement can also reference to statements and not just to resources.
Any other suggestions?

So far, an icon is a (short) string (e.g. allowing to specify UTF-8 characters), but @oalt proposes to allow a link to a graphical icon.

Today, the title of dataType, propertyClass, resourceClass and statementClass may have a single- or a multiple-language value. Therefore, a "select by title" operation is not straight forward.

@oalt proposes: Any title of dataType, propertyClass, resourceClass and statementClass can only be a string. The use of a vocabulary term is preferred.

I think it makes sense to have an additional value "System" in the Enumeration for the DT-Discipline to assign a requirement to a mechatronic System or a mechatronic control chain.

@odungern: What do you mean? Should we add such a value?

Definition reference: classDefinitions/102_EnumDatatypes.specif

Issue

In SpecIF some data elements are stored as flat lists on the top level (dataTypes, resourceClasses, statementClasses, hierarchyClasses), but the property classes and node elements from the hierarchies are no flat structures. They are inside the JSON as tree structures.

Proposal

Provide all data elements as flat structures and use references - similar to the resourceReference in an node element to reference to the needed element. A storage in a simple list makes it easier to find an element (e.g. in a hierarchy), because you do not need to search a tree structure with a DFS or BFS algorithm. The second Advantage would be, that all data is represented in the same way in SpecIF: as an Array of objects on the top level.

In branch 'master' for v0.11.x and later, an item may have multiple revisions.

For items, the following rules apply:

• If there are items with the same id, they all must specify a revision.
• All revisions of the same item must be different (the key consisting of id and revision must be unique).
• All revisions of any item must be >0.

For references (such as 'subject' or 'object' in statements), the following rules apply:

• If the reference does not specify a revision, the latest revision of the item is taken.
• If the reference specifies a revision=0, the latest revision of the item is taken (thus a revision=0 may only be found in a reference).
• The item referenced by id and revision must be present in the project or file.

ToDo: Upgrade the constraint check to enforce these rules.

As dataTypes (among other purposes) serve for checking user input of SpecIF model editors, a type for URIs resp. URLs would help.
For example, if a property has a dataType 'xs:dateTime' or 'xs:integer', a key-by-key input check may determine using a regex whether the user-input is valid. The same is possible, if there is a dataType as known in XML, see xs:anyURI.

I think the properties "PC-SupplierStatus", "PC-SupplierComment", "PC-OemStatus", "PC-OemComment" in the property class IREB:Requirement are to specific for a general definition of requirements. So I would suggest to remove them for the moment.

Idea

As I thought about that, I had the idea if it makes sense to introduce an inheritance mechanism to SpecIF for the classes. This would provide the ability to define a general IREB:Requirement and a more special "Automotive Requirement" by just adding the newly needed properties ("PC-SupplierStatus", "PC-SupplierComment", "PC-OemStatus", "PC-OemComment") and inherit the rest from the base class. In the resource class we then have a new value e.g. extends: "RC-Requirement".

ReqIF has the possibility to define a default value to an ATTRIBUTE-TYPE. These are assumed by the instance ATTRIBUTE, if it has no value.
To allow a 100% transformation between ReqIF and SpecIF, we would need default values for propertyClasses.

Define the properties of the properties of the items in 'files', such as:

"files": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "In case of a file, the id is ideally an absolute or relative URL.",
        "$ref": "#/definitions/id"
      },
      "title": {
        "type": "string"
      },
      "type": {
        "description": "The media type of the file (formerly MIME-type) according to https://www.iana.org/assignments/media-types/media-types.xhtml.",
        "type": "string"
      },
      "changedAt": {
        "$ref": "#/definitions/dateTime"
      },
      "changedBy": {
        "type": "string"
      }
    },
    "required": [ "id", "title", "type", "changedAt" ]
  }
}

An inheritance relation is helpful to maintain consistent class definitions. The idea is that an instance (e.g. resource) of a certain class (resourceClass in this case) may use all propertyClasses of the chain of ancestor classes. The same applies to subjectClasses and objectClasses in case of statements.

Hello @odungern !

In my IDE there is an example of a JSON configuration file where at the beginning a property "$schema" with a schema reference is included.

Example:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:60827",
      "sslPort": 44393
    }
  }, ...

What do you think - should we include such a property in each SpecIF file as well?

Extend the data structure for nodes with a description item. All other data types have such a description:

"description": {
            "type": "string"
}

I had missed that also in ReqIF, because when you implement tools and you have to verify that the generated data is correct, you have no possibility to store helpful information for human readers in the nodes. So the information in a nodes description item is not at first for a tool for display this information, but more for usage for testing and debugging purposes. Of course you can also use it to place helpful internal information for a different purpose at all.

The distinction between unformatted and formatted text comes from ReqIF. But thinking a little further brings me to the conclusion, that the distinction is irrelevant, because in practice there are formatted property values without formatting and unformatted property values may eventually be displayed as HTML. Also, Markdown is quite popular and a very good choice for formatting text; creating another datatype for Markdown doesn't make sense.

Therefore I propose to eliminate the dataType 'xhtml'. It must be possible to reformat the content without changing the dataType. If someone wants to use the text values, he may decide what to do: strip the formatting to get plain text, convert the formatting to or from Markdown resp. XHTML.

@oalt @oeichmann @S-Ruesch : What do you think?
Oskar

Rework and finalize the Diagram Interchange specification using SVG and metadata for SpecIF release 1.1

See XML Schema Part 2: Datatypes Second Edition, for example XSD:Boolean instead of xs:boolean.

In the class definitions I have created a new property class "dcterms:abstract" and applied it to the SpecIF:Diagram resource. The reason for this is, that I searched for a possibility to separate the representation of the diagram image (SVG, PNG etc.) information from a descriptional text. E.g. in UML-tools you have the graphical diagram and additionally you can give a descriptional formatted text.
@odungern : Do you agree with that change?

I propose the following to make the schema more consistent:

• rename enumerated dataType value from 'title' to 'value' .. which it is in the end. Rationale: all content, which may be provided in differrent languages, is called 'value'.
• remove requirement for 'title' in case of resources and statements ... and add it to propertyClass. Rationale: For resources and statements the title is redundant, if there are properties. In case of the properties, the title can be taken from the respective propertyClass in case of default.
• add 'files' to the list of required top level elements ... or remove 'statements'.

@oalt : what do you think? Agree?

When writing the documentation of the SpecIF-metamodel some questions came in my mind:

• What means the type attribute for the Email element?
• What means the type attribute for the Rights element?
• When the data type XHTML is no longer used, how is it expressed, that a string contains XHTML formatted text?

We have discussed the requirement of multiple values per property. In fact, we already have all the ingredients: 'multiple' flag for enumerated values and value lists for multi-language strings.

• Currently we say for a single value:
  "value": "single-value"
• and in case of a multivalued enumeration:
  "value": "value-id-1,value-id-2".
• For a multilanguage string we use:
  "value": [{"text":"content","language":"en"},{"text":"Inhalt","language":"de"}]
• So we could take just a list with strings for multiple values of any type:
  "value": ["value-1","value-2","value-3"].

However I propose to limit the variations of the "value" attribute and make it a list in all cases with one or more values.

• An enumeration would look like:
  "value": ["value-id-1","value-id-2"]
  which is anyways better than before!
• A multi-valued property of any kind would be
  "value": ["value-1","value-2","value-3"]
• and the multi-language string will not change.
• A single-valued property, however, would look like:
  "value": ["single-value"]

What do you think: @oalt @oeichmann @S-Ruesch ?

The Tutorial 6: 'Very Simple Model (FMC)' shows following diagram:

When I open the SpecIF viewer at https://specif.de/apps/view#view=doc;project=ACP-Very-Simple-Model-FMC;node=N-MEl-50fbfe8f0029b1a8016ea86245a9d83a, I get following output:

That means, no diagram is shown at all.

The root resource (https://specif.de/apps/view#view=doc;project=ACP-Very-Simple-Model-FMC;node=N-Diagram-aec0df7900010000017001eaf53e8876) shows a diagram:

I really like that diagram as the syntax is 100% FMC Block Diagram (and not something custom as in tutorial 6)

Values:

• public
• private
• protected (?)

What do you think: @oalt ?

Replace the multi-language title type for the File element with a simple string. It makes no sense here to have multi-language values for a file name or a URL.

In some code segments there is still an assumption that revisions are ascending integers.

For v1.0, 'changedAt' has been added to the required properties of a node (a nodes' item). Of course it will be set, when a node is created or modified.
But in fact. also the parent is changed, if a node is added or moved So also set the changedAt of the parent? I propose not to do so, also because at root level, there is no parent. This feel a little strange, when moving a node with PUT and specifying parent resp. predecessor. Then the moved node gets a new change date, but not the affected parent nodes.
Have an opinion, @oalt, @oeichmann and @S-Ruesch ?

Currently the revision is of type 'integer'. Thus, only sequential numbering is possible, but no branching. Also, document-databases have a more elaborated designation of revision.

Proposal: Change to 'string' and require that any newer revision is sorted in lexical order after any older.

@oalt : What do you think?

While it is not necessary to construct a working data set without node ids, the API needs it to offer operations to modify the hierarchy. Inserting a node needs a 'parent' (to create a lower level) or 'predecessor' (to insert at the same level), and the only unambiguous way to identify a node is by id (a resource may be referenced multiple times in a hierarchy).
Thus we should require a node id with v1.0.

Makes it sense to apply the property 'PC-Stereotype' to each SpecIF resource class or is this restricted to a specific subset? Which practical experience is available using the stereotype property?

Why are some numerical data type values in the Base Definitions restricted to a specific range?

• DT-Integer
• DT-Real
• DT-Decimal2
  I would not restrict these data types ind the Base Definitions, because I think in practice we will have bigger numerical values to store.

Issue

When SpecIf is used as data format in a backend database, you will have many hierarchy objects containing requirement documents, BOMs etc.
Currently the hierarchy objects are just an array of hierarchies. Normally engineering data is organized and assigned to projects or specific systems. So it would be helpful, when you have a possibility to organize hierarchies in a tree structure with folders (headings), perhaps paragraphs and hierarchies, too - similar to file systems or repositories of MBSE tools.

Proposal

Extend SpecIF with a new type called "repositories" on the same level as the other data types (e.g. hierarchies) and use the same concept as used for hierarchies to link to hierarchies using recursive nodes. Because of a hierarchy can also have properties, we can use a hierarchy object as well to represent a folder/directory.

Represent a revision as a tuple of data

• branch name
• revision ID (e.g. a hash)

Each revision is unique following this schema. The following rules shall be always followed by all SpecIF providers:

1. If the replaces is empty, the element is the first one in the branch stated in the revision
2. If the element is not the first element in the given branch the replaces must always been set

Some vocabulary elements have currently no title defined:

• Comment
• Paragraph - The title can be used as marginal note

I would suggest to make the dcterms:title property mandatory for each Resource, so a tool can always use it as tree node name in a hierarchy view.

If no title is available in the source tool, a SpecIF adapter shall set a dummy title or an empty string.

Implement the schema for dataTypes with specific cases for each of the data-types with the respective properties using a "oneOf" structure.

Use Github actions to create a specification document automatically.

The idea is to provide separate schemata for the SpecIF elements, such as 'dataType', 'resourceClass' or 'resource'. Separate schemata can be used by an API to check incoming data.

There are two alternatives:

• JSON Schema allows to separate a schema into multiple files. Then, a schema for each SpecIF element is provided and the SpecIF schema references them.
• Keep the SpecIF schema as it is and to provide element-schemata in addition. Advantage is that a single schema file is quicker to load and disadvantage is that duplicate definitions need to be maintained in parallel.

In SpecIF you can define the property values in different languages or use a simple string if you do not need multiple languages.
To ensure the compatibility and the ability to convert data from simple string to multi-language representation and vice versa, an information about the used language in the string value is required.

My first idea was to define a new JSON property "defaultLanguage" in the SpecIF heading data. But the problem is, that if you use SpecIF as API data you will not always get a complete SpecIF data structure, but just a Resource, Statement or Property alone.

So the proposal is to extend the "value" for a SpecIF property with a new JSON property "defaultLanguage":

 "defaultLanguage": {
            "description": "An IETF language tag such as 'en', 'en-US, 'fr' or 'de' - specifying the default language used for this value.",
            "type": "string"
          }