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)
      "schemaLocation" : "schemas/maindoc/UBL-PriorInformationNotice-2.3.xsd", (15)
      "additionalNamespaces" : [ (16)
        {
          "prefix" : "cac", (17)
          "uri" : "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2", (18)
          "schemaLocation" : "schemas/common/UBL-CommonAggregateComponents-2.3.xsd" (19)
        },
        ...
      ]
    },
    ...
  ]
}
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.
15 Location of the XSD file that contains the definition of the root element, relative to the root of the SDK.
16 Additional namespaces used in an XML instance of the document type.
17 Prefix to use in the declaration of the additional namespace.
18 Full URI of the additional namespace.
19 Location of the XSD file that contains the definition of the elements in the namespace, relative to the root of the SDK.

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 this root element is in the file indicated by the schemaLocation property.

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-137-Lot")

_captionFieldId

Appears only if _repeatable is true. This property provides the identifier of the field that can be used to help a user recognise a specific instance of this repeatable group, like a name or title. 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-21-Lot")

_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")

_schemeName

Appears only if _repeatable is true. Indicates the name of the scheme associated with the field in this group where the identifier of the group must be stored. The value can be retrieved through the field metadata (fields.json) but is provided also here for convenience.
value: an schemeName 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

_presetValue

The known value that should be used to pre-fill this field in your application.
value: a string value, which must be converted to the type of the field. "{NOW}" corresponds to the current date or time.

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.