Field Guide
This section describes the terms used in Parameters API.
Overview
Parameters API stores parameter data within a Forma hub. Today, the primary management experience is available through Autodesk Forma hub administration. Parameters are organized by two layers of grouping: the first level under the hub is called “groups”, and the second “collections”. Currently, a hub may contain only one “group”. (This feature is reserved for future enhancement.) Each “group” can have multiple collections. The image below depicts the structure.
A “parameter” is defined by its name and data type, and typically has additional metadata, such as a category and labels.
In the following, we explain each of these terms.
Organizational Structure of Parameters: - Parameter Group - Collection - Parameter
Composition of Parameter Metadata: - Spec - Unit - Label - Category - Classification Group
Parameter group
| id string: UUID | The group ID. |
| title string | The group title. |
| description string | The group description. |
| createdBy string | The user who created the group. |
| createdAt string | The date that the group is created. |
| updatedBy string | The user who updated the group. |
| updatedAt string | The date that the group is updated. |
Relationships
hub1-to-1 | parent hub for this parameter collection |
collections1-to-many | parameters contained within the parameter collection |
Example Object
{
"id": "c23b5198ae2840a3a8ccc679903254c6",
"title": "My Sample Group",
"description": "This is my 1st sample group",
"createdBy": "zlR4YAiokL302TZcopusRB0gHYBoaQGs",
"createdAt": "2023-04-26T13:39:01+0000",
"updatedBy": "WXE5QKQJUPV7",
"updatedAt": "2023-04-27T04:27:57+0000"
}
Parameter collection
| id string: UUID | The collection ID. |
| name string | The collection name. |
| permissions array: string | The permissions of the user to access the parameters It could be read, write ,or admin. |
Relationships
group1-to-1 | parent group for this parameter collection |
parameters1-to-many | parameters contained within the parameter collection |
Example Object
{
"id": "02826a53ec-134b-0c98-0ab8-4af7a91214",
"title": "Education Project Collection",
"description": "Contains parameters for all education projects",
"permissions": {
"read": true,
"write": false,
"admin": false
}
}
Parameter
| id string | The parameter ID. |
| name string | The parameter name. |
| description string | The parameter description. |
| specId string | The parameter spec ID. |
| readOnly boolean | Indicates if the parameter is to be treated as read-only or not by a UI client. Immutable once set. |
| metadata array: object | The parameter metadata. It may vary from one product to another.
For example, to support the use of a parameter in Revit, the metadata object might record category bindings and an instance/type assignment.
|
| anyOf | |
| 0 object | An object with a string ID and a Boolean value. The ID could be one of the below:
“isHidden” to indicate if the parameter is hidden or not in the application.
“isArchived” to indicate if the parameter is archived or not.
|
| id string | The metadata ID. |
| value boolean | Boolean value of the metadata. |
| 1 object | An object with a string ID and an enumerated string value.
The ID could be “instanceTypeAssociation” to indicate if the parameter is associated with element instances, element types, or neither.
Possible values: NONE, INSTANCE, TYPE |
| id string | The metadata ID. |
| value string | The metadata value. |
| 2 object | An object with a string ID and a string array value. The ID could be “labelIds” to list all the labels attached to this parameter. |
| id string | The metadata ID. |
| value array: string | The metadata value. |
| 3 object | An object with a string ID and an object value. The ID could be “group” to indicate the group for this parameter. |
| id string | The metadata ID. |
| value object | The metadata value. |
| bindingId string | The binding ID of the group, which can be looked up in the results of the GET /classifications/groups API. |
| id string | The group ID, which can be looked up in the results of the GET /classifications/groups API. |
| 4 object | An object with a string ID and an object array. The ID could be “categories” to indicate the categories of this parameter. |
| id string | The metadata ID. |
| value array: object | The metadata value. |
| bindingId string | The category binding ID, which can be looked up in the results of the GET /classifications/categories API. |
| id string | The category ID, which can be looked up in the results of the GET /classifications/categories API. |
| 5 object | An object with a string ID and a string value. The ID could be “specCategoryId” to indicate the spec category ID of this family type parameter. |
| id string | The metadata ID. |
| value string | The metadata value. |
Relationships
parameter collection1-to-1 | parent parameter collection for this parameter |
spec1-to-1 | spec for the parameter |
label1-to-many | labels attached to this parameter |
category1-to-many | categories bind to this parameter |
group1-to-1 | group bind to this parameter |
Example Object
{
"id": "parameters.d05ec054ef8046ad9c80fc742f29027c:000ccf6716504165b73d20739f7dc1bf-1.0.0",
"name": "ArtificialLighting",
"description": ""
"specId": "autodesk.spec:spec.string-2.0.0",
"readOnly": false,
"metadata": [
{
"id": "isHidden",
"value": false
},
{
"id": "isArchived",
"value": false
},
{
"id": "labelIds",
"value": [
"ACSF-01105-DTLK-44382",
"ADJH-96226-GAKC-59763",
"ACSY-84419-DPLC-36868"
]
},
{
"id": "group",
"value": null
},
{
"id": "instanceTypeAssociation",
"value": "TYPE"
},
{
"id": "categories",
"value": [
{
"bindingId": "ACFT-94219-HCEE-04771",
"id": "autodesk.revit.category.family:doors-1.0.0"
}
]
},
{
"id": "specCategory",
"value": null
}
]
}
Spec
A spec describes a data type for user-facing presentation. Specs assist in specifying custom properties in design applications, so that end users may select the correct data type for a property. Examples of spec objects: Text, Yes/No, Image, Length, or Thermal Resistance.
A spec can be used to create a single or multiple select datatype for parameters when specifying an enumeration.
A spec object includes the following fields:
| id string | The parameter spec ID. |
| name string | The user-facing name of the spec. |
| disciplineId string | The discipline ID. Look up detailed information in the response of the GET /disciplines API. |
| applicableUnitIds array: string | The identifiers of the units applicable to this spec. This field exists only for measurable specs that are associated with units of measurement, such as “Length” or “Acceleration”. It is null for non-measurable specs such as “Text” or “Yes/No”. |
| storageUnitId string | The identifier of the storage unit of this spec. This field exists only for measurable specs that are associated with units of measurement, such as “Length” or “Acceleration”. It is null for non-measurable specs such as “Text” or “Yes/No”. The storage unit is the unit of measurement that quantifies values of this parameter in persistent storage. When writing parameter values, client applications must ensure that the values written are quantified according to each parameter’s storage unit. A unit conversion might be necessary if input values are quantified differently. |
| valueTypeId string | The identifier of the storage value type, which could be Bool, Int64, Float64, Reference, String or a type ID. Using an enumeration type ID will allow you to define a custom data type using an enumeration. |
| context string | For enumerations only. The intended use of the spec in a list, to pick a single value or multiple values from the enumeration. |
Specs allow version ranges to be defined for a valueTypeId. This allows enumerations to be updated and parameters using the spec will be able to get new data without changing the parameter’s version as well.
It is possible to specify a range of valid versions for a property. This may be valuable to allow some flexibility without introducing breaking changes.
Use >= to denote that you would like to accept any version greater than or equal to the specified version. For Example - “typeId”: “a.a:a->=1.0.1” would accept any version greater than or equal to 1.0.1.
Use ^ to denote that you would like to accept any version greater than or equal to the specified version, as long as it has the same major number. For Example - “typeId”: “a.a:a-^1.0.1” would accept any version greater than or equal to 1.0.1, but less than 2.0.0.
Use ~ to denote that you would like to accept any version greater than or equal to the specified version, as long as it has the same major and minor number. For Example - “typeId”: “a.a:a-~1.0.1” would accept any version greater than or equal to 1.0.1, but less than 1.1.0.
Relationships
parameter1-to-1 | the parameter using this spec |
discipline1-to-1 | the discipline for this spec |
unit1-to-many | the units associated with this spec |
enumeration1-to-1 | the enumeration used by this spec, if used as the spec’s valueTypeId |
Example Object
{
"id": "autodesk.spec.aec.electrical:apparentPower-2.0.0",
"name": "Apparent Power",
"disciplineId": "autodesk.spec.discipline:electrical-1.0.0",
"applicableUnitIds": [
"autodesk.unit.unit:watts-1.0.1",
"autodesk.unit.unit:kilowatts-1.0.1",
"autodesk.unit.unit:britishThermalUnitsPerSecond-1.0.1",
"autodesk.unit.unit:britishThermalUnitsPerHour-1.0.1",
"autodesk.unit.unit:caloriesPerSecond-1.0.1",
"autodesk.unit.unit:kilocaloriesPerSecond-1.0.1",
"autodesk.unit.unit:voltAmperes-1.0.1",
"autodesk.unit.unit:kilovoltAmperes-1.0.1",
"autodesk.unit.unit:horsepower-1.0.1"
],
"storageUnitId": "autodesk.unit.unit:watts-1.0.1"
}
Enumeration
An enumeration describes a user-defined list for creating specs that facilitate the single or multiple selection data type. Enumerations assist in specifying a custom list of options/values for a parameter to use. An enumeration object includes the following fields:
| id string | The enumeration ID. |
| name string | The user-facing name of the enumeration. |
| content map | A map of IDs and values for available options in the list. Look up detailed information in the response of the GET /enumerations API. |
Relationships
spec1-to-many | the specs using this enumeration |
Example Object
{
"id": "parameters.d05ec054ef8046ad9c80fc742f29027c:61712b031b1e49e897e3cf1643dea73f-2.0.0",
"name": "Streetlight Colors",
"Content": [
{
"id": "Red",
"value": 0
},
{
"id": "Yellow",
"value": 1
},
{
"id": "Green",
"value": 2
}
],
"createdBy": "FXA2K4JGR5BECGSR",
"createdAt": "2024-11-11T16:22:29+0000"
},
}
Unit
A unit defines a standard representation of units and formatting rules.
| id string | The unit ID. |
| name string | The unit name. |
| symbolIds array: string | The identifiers of symbols that indicate this unit in a written measurement, such as the “m” indicating “meters” in a written measurement such as “5m”. A unit of measurement may have zero, one, or many symbols available. Symbols may be used when rendering parameters. |
Relationships
spec1-to-1 | the parent spec |
symbol1-to-many | all the symbols of the unit |
Example Object
{
"id": "autodesk.unit.unit:feet-1.0.1",
"name": "Feet",
"symbolIds": [
"autodesk.unit.symbol:feetAndInches-1.0.1",
"autodesk.unit.symbol:footSingleQuote-1.0.1",
"autodesk.unit.symbol:ft-1.0.1",
"autodesk.unit.symbol:lf-1.0.1"
]
}
Label
A label is a meta-data that is attached to specific parameter that help search and filter parameters
| id string | The label ID. |
| name string | The label name. |
| description string | The label description. |
Relationships
parameters1-to-many | the parameters attached with the label. |
Example Object
{
"id": "ACMT-69415-CEVT-22201",
"name": "test",
"description": ""
}
Category
A category controls the organization, visibility, graphical representations, and scheduling options of Families within the Project.
| id string | The category ID. |
| name string | The category name. |
| disciplineIds array: string | The discipline IDs of this category. Look up detailed information in the response of the GET /disciplines API. |
| parentCategoryId string | The parent category ID of this category. |
| bindingId string | The bindingId of this this category. It is used to create the parameters with categories, which will help to organize the parameters in different categories in the application, like Revit. The category can’t be bound to any parameters if the bindingId is null. |
Relationships
parameter1-to-1 | the parameter associated with this category |
discipline1-to-many | the disciplines for this category |
Example Object
{
"id": "autodesk.revit.category.family:fireProtection-1.0.0",
"name": "Fire Protection",
"disciplineIds": [
"autodesk.spec.discipline:architecture-1.0.0",
"autodesk.spec.discipline:structural-1.0.0",
"autodesk.spec.discipline:hvac-1.0.0",
"autodesk.spec.discipline:electrical-1.0.0",
"autodesk.spec.discipline:piping-1.0.0",
"autodesk.spec.discipline:infrastructure-1.0.0"
],
"parentCategoryId": null,
"bindingId": "ACFT-94213-BNDF-85095"
}
Classification Group
A classification group helps to organize the parameters in the application, like Revit property pallet group.
| id string | The classification group ID. |
| name string | The classification group name. |
| bindingId string | The binding ID of this group. It is used to create parameters with group binding, which will help to organize the parameters in different groups in the application, like Revit. The group can’t be bound to any parameters if the bindingId is null. |
Relationships
parameter1-to-1 | the parameter associated with this group |
Example Object
{
"id": "autodesk.parameter.group:adskModelProperties-1.0.0",
"name": "Model Properties",
"bindingId": "ABXZ-68714-GYLB-48622"
}
Limitations
The following list details known limitations of the current release of the Parameters API:
- Search APIs will return a (200) response even if it returns with errors in the response instead of a (207)
- Attach Labels API will return a (201) response even if it returns with errors in the response instead of a (207)
- Detach Labels API will return a (204) response even if it returns with errors in the response instead of a (207)
- Update or Detach Labels APIs can update parameters outside the specified collection in certain instances.