Notice Types

Notice subtypes

The eForms Regulation defines, in table 1 of its annex, a list of types of procurement notices.

In order to avoid confusion with the more general notion of "notice type" (contract notice, contract award, PIN, etc.), we are designating each specific item as "notice subtype". So a notice subtype corresponds to a specific column in table 2 of the annex to the eForms regulation.

The eForms SDK provides this information in the notice-types folder, as a structured JSON file named notice-types.json.

This file contains some metadata, followed by the list of notice subtypes, and the indication of the corresponding XML schema.

Structure of notice-types.json

{
  "ublVersion" : "2.3", (1)
  "sdkVersion" : "eforms-sdk-0.5.0", (2)
  "metadataDatabase" : { (3)
    "version" : "0.2.16",
    "createdOn" : "2021-11-04T11:11:11"
  },
  "noticeSubTypes" : [
    {
      "documentType" : "PIN", (4)
      "legalBasis" : "32014L0024", (5)
      "formType" : "planning", (6)
      "type" : "pin-buyer", (7)
      "description" : "Notice of the publication of a prior (...)", (8)
      "subTypeId" : "1", (9)
      "_label" : "notice|name|1", (10)
      "viewTemplateIds" : [ "1", "summary" ] (11)
    },
    ...
  ],
  "documentTypes" : [
    {
      "id" : "PIN", (12)
      "namespace" : "urn:oasis:names:specification:ubl:schema:xsd:PriorInformationNotice-2", (13)
      "rootElement" : "PriorInformationNotice" (14)
    },
    ...
  ]
}

1	Version of the UBL standard used.
2	Version of the eForms SDK the file belongs to.
3	Version number and date of the data used to create this file.
4	Document type of the notice subtype, used to determine the XML namespace and root element of the XML notice.
5	Legal basis for the notice subtype.
6	The standard form for the notice subtype.
7	The notice type for the notice subtype. Values are from the "notice type" codelist.
8	Description of the notice subtype, from the eForms regulation.
9	Identifier of the notice subtype.
10	Identifier of the label for the name of the notice subtype. The label is available in the translations folder.
11	List of identifiers of the view templates that can be used to visualise a notice of this subtype.
12	Identifier of the document type.
13	XML namespace for the document type.
14	Root XML element for the document type.

From the information visible in the example above, we can see that the notice subtype 1 has the document type PIN, so the root element in the XML is PriorInformationNotice. The definition of each root element is in the corresponding file present in the folder schemas/maindoc in the eForms SDK.

Definition of a notice subtype

For each notice subtype, we define the content and structure of the form that notice authors will fill in. We provide this definition as a set of JSON files, with one file per notice subtype. Those files are available in the eForms SDK, in the folder /notice-types, and are named as follows: <subTypeId>.json

These files reference the fields contained in the form via their identifier. The information for every field is centralised in the field repository.

Overall structure

The definition of a notice subtype has 2 parts:

metadata, contains a flat list of readonly or hidden fields the values of which are known before the notice is created (and therefore can be pre-filled).
content, contains the fields that should be rendered on the screen for notice authors to fill-in. The fields are organised in nested groups providing in this way a hierarchical structure that the notice author should be presented with, in order to navigate the notice while filling it in.

{
  "ublVersion" : "2.3",
  "sdkVersion" : "0.7.0",
  "metadataDatabase" : {
    "version" : "0.4.179",
    "createdOn" : "2022-06-30T17:37:21"
  },
  "noticeId" : "10", (1)
  "metadata" : [ (2)
    {
      "id" : "BT-02-notice",
      "contentType" : "field",
      "displayType" : "COMBOBOX",
      "description" : "Notice Type",
      "_label" : "field|name|BT-02-notice",
      "readOnly" : true
    },
    ...
  ],
  "content" : [ { (3)
    "id" : "GR-ContractingAuthority",
    "contentType" : "group",
    "displayType" : "SECTION",
    "description" : "Contracting Authority",
    "_label" : "group|name|GR-ContractingAuthority",
    "content" : [
      ... (4)
    ]}
  ]
}

1	`noticeId` is the notice subtype identifier (the same as the filename).
2	`metadata` is a flat list of fields with known values.
3	`content` is a hierarchical list of of "content elements" (`fields` organised in a hierarchy of `groups`) forming the visual structure of the notice..
4	Content elements can be nested.

Structure of `metadata` Section

The metadata section is a flat list of fields, the values of which are known before the notice is created. The fields are either marked as readOnly or hidden. A field is marked as _repeatable if it can occur multiple times in the metadata.

[
  {
    "id" : "BT-02-notice",
    "contentType" : "field",
    "displayType" : "COMBOBOX",
    "description" : "Notice Type",
    "_label" : "field|name|BT-02-notice",
    "readOnly" : true
  }, {
    "id" : "BT-03-notice",
    "contentType" : "field",
    "displayType" : "COMBOBOX",
    "description" : "Form Type",
    "_label" : "field|name|BT-03-notice",
    "readOnly" : true
  }, {
    "id" : "BT-04-notice",
    "contentType" : "field",
    "displayType" : "TEXTBOX",
    "description" : "Procedure Identifier",
    "_label" : "field|name|BT-04-notice",
    "readOnly" : true
  },
   ...
]

Structure of `content` Section

A content element can either represent a field or a group of fields as indicated by its contentType property. A content element of type group can contain nested group elements (as well as field elements).

Every field element represents a valid eForms field. The id property of field elements always contains the eForms field’s identifier and can be used to retrieve the field’s metadata from the field repository (fields.json).

Every group element is primarily a visual/logical structure element. However, in some cases, a group element may also correspond to an XML element (node) in the notice XML file. In this case, a nodeId property is provided indicating the identifier of the node which can be used to retrieve node metadata from the xmlStructure section of fields.json.

The identifiers of group elements (indicated by their id property) always start with "GR-" and, (in contrast with the identifiers of field elements), do not point to any elements in fields.json. They are used however to encode the 'group` labels (translations).

 "content" : [ {
    "id" : "GR-ContractingAuthority",
    "contentType" : "group",
    "displayType" : "SECTION",
    "description" : "Contracting Authority",
    "_label" : "group|name|GR-ContractingAuthority",
    "content" : [ {
      "id" : "GR-ContractingAuthority-Buyer",
      "contentType" : "group",
      "nodeId" : "ND-ContractingParty",
      "displayType" : "GROUP",
      "description" : "Contracting Party related Information (URL, Legal Type, Contracting Type, Activity, …)",
      "_label" : "node|name|ND-ContractingParty",
      "_repeatable" : true,
      "content" : [ {
        "id" : "OPT-300-Procedure-Buyer",
        "contentType" : "field",
        "displayType" : "TEXTBOX",
        "description" : "Buyer Technical Identifier Reference",
        "_label" : "field|name|OPT-300-Procedure-Buyer"
      }, {
        "id" : "BT-11-Procedure-Buyer",
        "contentType" : "field",
        "displayType" : "COMBOBOX",
        "description" : "Buyer Legal Type",
        "_label" : "field|name|BT-11-Procedure-Buyer"
      }, {
        "id" : "BT-10-Procedure-Buyer",
        "contentType" : "field",
        "displayType" : "COMBOBOX",
        "description" : "Activity Authority",
        "_label" : "field|name|BT-10-Procedure-Buyer"
      }, {
        "id" : "BT-508-Procedure-Buyer",
        "contentType" : "field",
        "displayType" : "TEXTBOX",
        "description" : "Buyer Profile URL",
        "_label" : "field|name|BT-508-Procedure-Buyer"
    },
    ...
    ]
  },
  ...
  ]
},
...
]

The following table lists all available properties for groups and fields:

Properties of `group` elements

`id`	The identifier of the group. value: a text string prefixed by "GR-"
`description`	The description of the `group` element in english. The property is included for the convenience of anyone reading the file. It should not be used by your application (see `_label` property). value: a text string
`contentType`	Indicates that this content element is a group element. value: `"group"`
`displayType`	Indicates whether this `group` element should be rendered as a notice section rather than a simple group of fields. Only root level groups can be marked as notice sections. value: `"GROUP"` or `"SECTION"`
`nodeId`	The property is only present in `group` elements that can be associated with a `node` in the xmlStructure. When present, it indicates the identifier of the corresponding `node` which can be used to retrieve further node metadata from `fields.json`. value: a `node` identifier (a text string like `"ND-LotResult"`)
`_identifierFieldId`	Appears only if `_repeatable` is `true`. This property provides the identifier of the field that should be used to store the identifier generated for each instance of this repeatable `group`. The `identifierFieldId` can be retrieved through metadata of the associated `node` (`fields.json`) but it is provided also here for convenience. value: a `field` identifier (a text string like `"BT-11-Procedure-Buyer"`)
`_idScheme`	Appears only if `_repeatable` is `true`. Indicates the identifier scheme associated with the field in this `group` where the identifier of the `group` must be stored. It should be used as a prefix of identifiers generated for the instances of this repeatable group (e.g. `"LOT-0001"`). The value can be retrieved through the `field` metadata (`fields.json`) but is provided also here for convenience. value: an `idScheme` identifier (a text string like `"LOT"`)
`_repeatable`	Indicates that the user should be allowed to add multiple occurrences of this `group` element. The property is present only when its value is `true` (different than its default value). A repeatable `group` element is always associated with a repeatable `node`. The value can be retrieved from the `node` metadata (`fields.json`) but is also provided here for convenience. values: `true` or `false` (default)
`_label`	The identifier of the label that should be used for this `field` in the user interface of your application. value: a label identifier

Properties of `field` elements

`id`	The identifier of the eForms field associated with this `field` element. As every eForms field appears once in every notice subtype, the field’s identifier is used to also identify the `field` element itself. value: a text string (matching the identifier of an existing field).
`description`	The description of the `field` element in english. The property is included for the convenience of anyone reading the file. It should not be used by your application (which should instead use the appropriate translation indicated by the `_label` property). value: a text string
`contentType`	Indicates that this content element is a `field` element. value: `"field"`
`displayType`	Provides a hint on what type of input element should be displayed on the screen for filling the field. value: `TEXTBOX`, `TEXTAREA`, `COMBOBOX`, `RADIO`, or `CHECKBOX`
`readOnly`	Indicates whether or not the field should be editable by the user. The property is present only when its value is `true` (different than its default value). values: `true` or `false` (default)
`hidden`	Indicates whether or not the field should be visible on the user’s screen. The property is present only when its value is `true` (different than its default value). values: `true` or `false` (default)
`valueSource`	This property indicates that the value of this field should be a copy of the value of another field. It provides the identifier of the referenced field whose value should be copied over. It is most commonly used for hidden fields of type `id-ref`. value: any string (e.g. `"BT-137-LotsGroup"`)
`_idScheme`	It appears only for the fields of type `id` (identifier) which are intended to store the identifier of a repeatable `group` element. The value can be retrieved from the `field` metadata (`fields.json`) but is also provided here for convenience. value: any string (e.g. `"LOT"`)
`_idSchemes`	This property appears only for fields of type `id-ref` (identifier reference). Such fields will typically have their `displayType` set to `COMBOBOX` with the intention of providing the user with a list of valid existing identifiers to chose from. The property provides a list of identifier prefixes (`idSchemes`) that can be used to find all available valid identifiers in the notice which can be used to populate the options of the combobox. The value can be retrieved from the `field` metadata (`fields.json`) but is also provided here for convenience. value: any string (e.g. `"LOT"`)
`_repeatable`	Indicates whether or not the user should be allowed to create multiple instances of this field. The property is present only when its value is `true` (different than its default value). values: `true` or `false` (default)
`_label`	The identifier of the label that should be used for this `field` in the user interface of your application. value: a label identifier

Property names starting with underscore

You may be wondering why some property names (like _repeatable) start with an underscore, while others (like hidden or readOnly) do not. What is the difference?

The difference is that the _repeatable property is a complementary property that could have been omitted without any information loss. This is because a group element is repeatable if and only if it is associated with a repeatable node. Therefore using the provided nodeId property value, one can always determine whether the group should be repeatable or not, by looking up the information in the xmlStructure (in fields.json).

However, having to look-up some specific additional information is very common while processing this file. For convenience, we decided therefore to include some complementary properties that help you avoid some common look-ups. To make these properties stand-out we decided to use a slightly different naming convention: starting their names with an underscore character (_).

JSON and XML structure constraints

The purpose of the notice subtype definition is to abstract the form displayed to a notice author from the eForms XML notice generated by the system. While it can be slightly customized, it cannot have an arbitrary structure, it must be aligned with the eForms XML schema to some extent.

For instance, the number of repeatable groups (in a path from the content root to a field) in the JSON structure must match the number of repeatable parent elements (in a path from the document root to the field element/attribute) in the eForms XML schema.

There is no constraint on non-repeatable groups. An arbitrary number of intermediate, non-repeatable groups can be created to organize the notice fields in a more convenient way. Moreover, the fields of the same level of the repeatable structure (ignoring non-repeatable groups) can be specified in an arbitrary order.

It is even possible to split a repeatable XML element group into multiple repeatable JSON groups. In such case, the XML element group must contain an (instance) identifier field (e.g. BT-137-Lot - Purpose Lot Identifier), which is also contained in every JSON group part.

Notice Types

Notice subtypes

Definition of a notice subtype

Overall structure

Structure of metadata Section

Structure of content Section

Properties of group elements

Properties of field elements

JSON and XML structure constraints

Structure of `metadata` Section

Structure of `content` Section

Properties of `group` elements

Properties of `field` elements