From 41add820be360b6ca161249c143ff610107de2fc Mon Sep 17 00:00:00 2001 From: Romain Date: Mon, 20 May 2019 09:29:43 +0200 Subject: [PATCH 1/2] Update swagger.yaml Updated accordoing to elements agreed in usse #9: - Change the name of the resource to make it a plural : unitsOfMeasure. - Update all parameters to camelCase - Change the name of one parameter that had a slash in the middle, Update description to contain the old name as information. - Add the descriptions based on the documentation from UN/CEFACT - Remove Status parameter/property - Change commonCode parameter type from query to path --- docs/recommendation-20/swagger.yaml | 321 +++++++++++++++++++++------- 1 file changed, 248 insertions(+), 73 deletions(-) diff --git a/docs/recommendation-20/swagger.yaml b/docs/recommendation-20/swagger.yaml index 137553f..afbee82 100644 --- a/docs/recommendation-20/swagger.yaml +++ b/docs/recommendation-20/swagger.yaml @@ -16,73 +16,152 @@ info: servers: - url: "https://codelists.api.edi3.org/recommendation-20" paths: + /quantityCategory/{commonCode}: + get: + tags: + - quantityCategory + summary: get a unit of measure from a code as defined in rec 20 - source is quantityCategory + description: "This api returns the details of a single unit of measure" + parameters: + - name: commonCode + in: path + required: true + schema: + type: string + description: | + This is the recommended single list of standard codes which is based on the following conventions. + + The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values + + - (a) alphabetic code values for units of measure as in UN/ECE + Recommendation No. 20, edition 1985; + + - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data + element number 355; + responses: + 200: + description: Successfull operation + content: + application/json: + schema: + $ref: '#/components/schemas/UnitOfMeasure' + example: + - commonCode: 10 + name: group + description: A unit of count defining the number of groups (group; set of items classified together). + category: 3.9 + 400: + description: ' Bad request - Issue with parameter' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d + error: pagesize needs to be between 1 and 1000. + 404: + description: No data found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 + error: No units of measure found + 500: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 + error: An unexpected exception occured /quantityCategory: get: tags: - quantityCategory - summary: Search for units of measure as defined in rec 20 + summary: Search for units of measure as defined in rec 20 - source is quantityCategory description: This api will return a (paged) list of units of measure codes - operationId: searchQuantityCategory parameters: - - name: GroupNumber + - name: groupNumber in: query description: "" schema: type: string - - name: Sector + - name: sector in: query - description: "" + description: "Name of the sector in plain english" schema: type: string - - name: GroupID + - name: groupID in: query description: "" schema: type: string - - name: Quantity + - name: quantity in: query description: "The name of the physical phenomenon being measured" schema: type: string - - name: Level/Category - in: query - description: "Identification of the normative or informative relevance of the unit" - schema: - type: string - - name: Status + - name: level in: query - description: "An indication of the maintenance status of individual units of measure" + description: | + Identification of the normative or informative relevance of the unit (Level / Category). + + - Level 1 - normative = SI normative units, standard and commonly used multiples + + NOTE: standard multiples are identified with "S" and commonly used multiples with "M" + e.g. "1 metre", "1S centimetre", "1M hectometre"). + + - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and + commonly used multiples. + + - Level 3 – informative = 9 categories of informative units (units of count and other + miscellaneous units), invariably with no comprehensive conversion factor to SI. + These units are provided for information and to facilitate the assignment and usage of + a common code value to represent such units. + - 3.1 Qualified base units from levels 1 and 2 + - 3.2 Sales units + - 3.3 Packing units + - 3.4 Shipping and transportation units + - 3.5 Industry specific units (various) + - 3.6 Information technology units + - 3.7 Integers/Numbers/Ratios + - 3.8 Multiples/Fractions/Decimals + - 3.9 Miscellaneous schema: type: string - - name: CommonCode + - name: commonCode in: query description: "This is the recommended single list of standard codes" schema: type: string - - name: Name + - name: name in: query description: "The name of the unit of measure" schema: type: string - - name: Description + - name: description in: query description: "A plain text specification of the named unit of measure" schema: type: string responses: 200: - description: OK + description: Successful Operation content: application/json: schema: - $ref: '#/components/schemas/QuantityCategories' + items: + $ref: '#/components/schemas/UnitOfMeasure' + type: array example: - GroupNumber: 01 Sector: Space and Time GroupID: 17 Quantity: solid angle Level/Category: 1S - Status: "" CommonCode: M55 Name: metre per radiant Description: Unit of the translation factor for implementation from rotation to linear movement. @@ -113,32 +192,115 @@ paths: example: identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 error: An unexpected exception occured - /unitOfMeasure: + /unitsOfMeasure/{commonCode}: + get: + tags: + - unitsOfMeasure + summary: get a unit of measure from a code as defined in rec 20 - source is units of Measure + description: "This api returns the details of a single unit of measure" + parameters: + - name: commonCode + in: path + required: true + schema: + type: string + description: | + This is the recommended single list of standard codes which is based on the following conventions. + + The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values + + - (a) alphabetic code values for units of measure as in UN/ECE + Recommendation No. 20, edition 1985; + + - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data + element number 355; + responses: + 200: + description: Successfull operation + content: + application/json: + schema: + $ref: '#/components/schemas/UnitOfMeasure' + example: + - commonCode: 10 + name: group + description: A unit of count defining the number of groups (group; set of items classified together). + category: 3.9 + 400: + description: ' Bad request - Issue with parameter' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d + error: pagesize needs to be between 1 and 1000. + 404: + description: No data found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 + error: No units of measure found + 500: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 + error: An unexpected exception occured + /unitsOfMeasure: get: tags: - - unitOfMeasure - summary: Search for units of measure as defined in rec 20 + - unitsOfMeasure + summary: Search for units of measure as defined in rec 20 - source is units of Measure description: This api will return a (paged) list of units of measure codes - operationId: searchUnitOfMeasure parameters: - - name: CommonCode + - name: commonCode in: query description: "This is the recommended single list of standard codes" schema: type: string - - name: Name + - name: name in: query description: "The name of the unit of measure" schema: type: string - - name: Description + - name: description in: query description: "A plain text specification of the named unit of measure" schema: type: string - - name: Level/Category + - name: level in: query - description: "Identification of the normative or informative relevance of the unit" + description: | + Identification of the normative or informative relevance of the unit (Level / Category). + + - Level 1 - normative = SI normative units, standard and commonly used multiples + + NOTE: standard multiples are identified with "S" and commonly used multiples with "M" + e.g. "1 metre", "1S centimetre", "1M hectometre"). + + - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and + commonly used multiples. + + - Level 3 – informative = 9 categories of informative units (units of count and other + miscellaneous units), invariably with no comprehensive conversion factor to SI. + These units are provided for information and to facilitate the assignment and usage of + a common code value to represent such units. + - 3.1 Qualified base units from levels 1 and 2 + - 3.2 Sales units + - 3.3 Packing units + - 3.4 Shipping and transportation units + - 3.5 Industry specific units (various) + - 3.6 Information technology units + - 3.7 Integers/Numbers/Ratios + - 3.8 Multiples/Fractions/Decimals + - 3.9 Miscellaneous schema: type: string responses: @@ -147,7 +309,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/UnitsOfMeasure' + items: + $ref: '#/components/schemas/UnitOfMeasure' + type: array example: - CommonCode: 10 Name: group @@ -189,57 +353,68 @@ components: type: string error: type: string - QuantityCategories: - type: array - items: - $ref: '#/components/schemas/QuantityCategory' - QuantityCategory: + UnitOfMeasure: type: object properties: - GroupNumber: - description: "" - type: string - Sector: - description: "" - type: string - GroupID: - description: "" - type: string - Quantity: - description: "The name of the physical phenomenon being measured" - type: string - Level/Category: - description: "Identification of the normative or informative relevance of the unit" - type: string - Status: - description: "An indication of the maintenance status of individual units of measure" - type: string - CommonCode: - description: "This is the recommended single list of standard codes" + commonCode: + description: | + This is the recommended single list of standard codes which is based on the following conventions. + + The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values + + - (a) alphabetic code values for units of measure as in UN/ECE + Recommendation No. 20, edition 1985; + + - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data + element number 355; type: string - Name: + name: description: "The name of the unit of measure" type: string - Description: + description: description: "A plain text specification of the named unit of measure" type: string - UnitsOfMeasure: - type: array - items: - $ref: '#/components/schemas/UnitOfMeasure' - UnitOfMeasure: - type: object - properties: - CommonCode: - description: "This is the recommended single list of standard codes" + level: + description: | + Identification of the normative or informative relevance of the unit (Level / Category). + + - Level 1 - normative = SI normative units, standard and commonly used multiples + + NOTE: standard multiples are identified with "S" and commonly used multiples with "M" + e.g. "1 metre", "1S centimetre", "1M hectometre"). + + - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and + commonly used multiples. + + - Level 3 – informative = 9 categories of informative units (units of count and other + miscellaneous units), invariably with no comprehensive conversion factor to SI. + These units are provided for information and to facilitate the assignment and usage of + a common code value to represent such units. + - 3.1 Qualified base units from levels 1 and 2 + - 3.2 Sales units + - 3.3 Packing units + - 3.4 Shipping and transportation units + - 3.5 Industry specific units (various) + - 3.6 Information technology units + - 3.7 Integers/Numbers/Ratios + - 3.8 Multiples/Fractions/Decimals + - 3.9 Miscellaneous type: string - Name: - description: "The name of the unit of measure" + sector: + description: "Name of the sector in plain english" type: string - Description: - description: "A plain text specification of the named unit of measure" + symbol: + description: "The symbol used to represent the unit of measure as in ISO 31 / 80000." type: string - Level/Category: - description: "Identification of the normative or informative relevance of the unit" + conversionFactor: + description: "Conversion factor to SI" + type: string + quantity: + description: | + The name of the physical phenomenon being measured. + + - (a) In levels 1 and 2 (SI or SI equivalent), the phenomena pertaining to a certain + category are listed under a heading giving the name of the relevant part in ISO 31; + - (b) In level 3 they are broken down into the 9 categories as defined below under + level/catgory. type: string - \ No newline at end of file From 852855e1d56761e3007cacd00bee78aec51940c6 Mon Sep 17 00:00:00 2001 From: Kseniya Shychko Date: Mon, 29 Jul 2019 02:24:02 +0300 Subject: [PATCH 2/2] add QuantityCategory schema adding back QuantityCategory per https://github.com/edi3/edi3-codelists/pull/14#issuecomment-500238258 also re-using some parameters and responses definitions --- docs/recommendation-20/swagger.yaml | 586 +++++++++++++--------------- 1 file changed, 269 insertions(+), 317 deletions(-) diff --git a/docs/recommendation-20/swagger.yaml b/docs/recommendation-20/swagger.yaml index afbee82..49d3d02 100644 --- a/docs/recommendation-20/swagger.yaml +++ b/docs/recommendation-20/swagger.yaml @@ -20,63 +20,29 @@ paths: get: tags: - quantityCategory - summary: get a unit of measure from a code as defined in rec 20 - source is quantityCategory + summary: | + Get a unit of measure from a code as defined in rec 20 - source is quantityCategory. description: "This api returns the details of a single unit of measure" parameters: - - name: commonCode - in: path - required: true - schema: - type: string - description: | - This is the recommended single list of standard codes which is based on the following conventions. - - The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values - - - (a) alphabetic code values for units of measure as in UN/ECE - Recommendation No. 20, edition 1985; - - - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data - element number 355; + - $ref: '#/components/parameters/commonCode' responses: - 200: + '200': description: Successfull operation content: application/json: schema: - $ref: '#/components/schemas/UnitOfMeasure' + $ref: '#/components/schemas/QuantityCategory' example: - commonCode: 10 name: group description: A unit of count defining the number of groups (group; set of items classified together). category: 3.9 - 400: - description: ' Bad request - Issue with parameter' - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d - error: pagesize needs to be between 1 and 1000. - 404: - description: No data found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 - error: No units of measure found - 500: - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 - error: An unexpected exception occured + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' /quantityCategory: get: tags: @@ -84,138 +50,48 @@ paths: summary: Search for units of measure as defined in rec 20 - source is quantityCategory description: This api will return a (paged) list of units of measure codes parameters: - - name: groupNumber - in: query - description: "" - schema: - type: string - - name: sector - in: query - description: "Name of the sector in plain english" - schema: - type: string - - name: groupID - in: query - description: "" - schema: - type: string - - name: quantity - in: query - description: "The name of the physical phenomenon being measured" - schema: - type: string - - name: level - in: query - description: | - Identification of the normative or informative relevance of the unit (Level / Category). - - - Level 1 - normative = SI normative units, standard and commonly used multiples - - NOTE: standard multiples are identified with "S" and commonly used multiples with "M" - e.g. "1 metre", "1S centimetre", "1M hectometre"). - - - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and - commonly used multiples. - - - Level 3 – informative = 9 categories of informative units (units of count and other - miscellaneous units), invariably with no comprehensive conversion factor to SI. - These units are provided for information and to facilitate the assignment and usage of - a common code value to represent such units. - - 3.1 Qualified base units from levels 1 and 2 - - 3.2 Sales units - - 3.3 Packing units - - 3.4 Shipping and transportation units - - 3.5 Industry specific units (various) - - 3.6 Information technology units - - 3.7 Integers/Numbers/Ratios - - 3.8 Multiples/Fractions/Decimals - - 3.9 Miscellaneous - schema: - type: string - - name: commonCode - in: query - description: "This is the recommended single list of standard codes" - schema: - type: string - - name: name - in: query - description: "The name of the unit of measure" - schema: - type: string - - name: description - in: query - description: "A plain text specification of the named unit of measure" - schema: - type: string + - $ref: '#/components/parameters/groupNumber' + - $ref: '#/components/parameters/sector' + - $ref: '#/components/parameters/groupID' + - $ref: '#/components/parameters/quantity' + - $ref: '#/components/parameters/level' + - $ref: '#/components/parameters/commonCodeQuery' + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/description' responses: - 200: + '200': description: Successful Operation content: application/json: schema: items: - $ref: '#/components/schemas/UnitOfMeasure' + $ref: '#/components/schemas/QuantityCategory' type: array example: - - GroupNumber: 01 - Sector: Space and Time - GroupID: 17 - Quantity: solid angle - Level/Category: 1S - CommonCode: M55 - Name: metre per radiant - Description: Unit of the translation factor for implementation from rotation to linear movement. - 400: - description: ' Bad request - Issue with parameter' - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d - error: pagesize needs to be between 1 and 1000. - 404: - description: No data found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 - error: No quantity measure found - 500: - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 - error: An unexpected exception occured + - groupNumber: 01 + sector: Space and Time + groupID: 17 + quantity: solid angle + level: 1S + commonCode: M55 + name: metre per radiant + description: Unit of the translation factor for implementation from rotation to linear movement. + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' /unitsOfMeasure/{commonCode}: get: tags: - unitsOfMeasure - summary: get a unit of measure from a code as defined in rec 20 - source is units of Measure + summary: get a unit of measure from a code as defined in rec 20 - source is units of Measure. description: "This api returns the details of a single unit of measure" parameters: - - name: commonCode - in: path - required: true - schema: - type: string - description: | - This is the recommended single list of standard codes which is based on the following conventions. - - The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values - - - (a) alphabetic code values for units of measure as in UN/ECE - Recommendation No. 20, edition 1985; - - - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data - element number 355; + - $ref: '#/components/parameters/commonCode' responses: - 200: + '200': description: Successfull operation content: application/json: @@ -226,33 +102,12 @@ paths: name: group description: A unit of count defining the number of groups (group; set of items classified together). category: 3.9 - 400: - description: ' Bad request - Issue with parameter' - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d - error: pagesize needs to be between 1 and 1000. - 404: - description: No data found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 - error: No units of measure found - 500: - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 - error: An unexpected exception occured + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' /unitsOfMeasure: get: tags: @@ -260,51 +115,12 @@ paths: summary: Search for units of measure as defined in rec 20 - source is units of Measure description: This api will return a (paged) list of units of measure codes parameters: - - name: commonCode - in: query - description: "This is the recommended single list of standard codes" - schema: - type: string - - name: name - in: query - description: "The name of the unit of measure" - schema: - type: string - - name: description - in: query - description: "A plain text specification of the named unit of measure" - schema: - type: string - - name: level - in: query - description: | - Identification of the normative or informative relevance of the unit (Level / Category). - - - Level 1 - normative = SI normative units, standard and commonly used multiples - - NOTE: standard multiples are identified with "S" and commonly used multiples with "M" - e.g. "1 metre", "1S centimetre", "1M hectometre"). - - - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and - commonly used multiples. - - - Level 3 – informative = 9 categories of informative units (units of count and other - miscellaneous units), invariably with no comprehensive conversion factor to SI. - These units are provided for information and to facilitate the assignment and usage of - a common code value to represent such units. - - 3.1 Qualified base units from levels 1 and 2 - - 3.2 Sales units - - 3.3 Packing units - - 3.4 Shipping and transportation units - - 3.5 Industry specific units (various) - - 3.6 Information technology units - - 3.7 Integers/Numbers/Ratios - - 3.8 Multiples/Fractions/Decimals - - 3.9 Miscellaneous - schema: - type: string + - $ref: '#/components/parameters/commonCodeQuery' + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/description' + - $ref: '#/components/parameters/level' responses: - 200: + '200': description: OK content: application/json: @@ -313,38 +129,138 @@ paths: $ref: '#/components/schemas/UnitOfMeasure' type: array example: - - CommonCode: 10 - Name: group - Description: A unit of count defining the number of groups (group; set of items classified together). - Level/Category: 3.9 - 400: - description: ' Bad request - Issue with parameter' - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d - error: pagesize needs to be between 1 and 1000. - 404: - description: No data found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 - error: No units of measure found - 500: - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 - error: An unexpected exception occured + - commonCode: 10 + name: group + description: A unit of count defining the number of groups (group; set of items classified together). + level: 3.9 + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' components: + parameters: + commonCode: + name: commonCode + in: path + required: true + schema: + type: string + description: | + This is the recommended single list of standard codes which is based on the following conventions. + + The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values + + - (a) alphabetic code values for units of measure as in UN/ECE + Recommendation No. 20, edition 1985; + + - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data + element number 355; + - name: groupNumber + in: query + description: "" + schema: + type: string + groupNumber: + name: groupNumber + in: query + description: "" + schema: + type: string + sector: + name: sector + in: query + description: "Name of the sector in plain english" + schema: + type: string + groupID: + name: groupID + in: query + description: "" + schema: + type: string + quantity: + name: quantity + in: query + description: "The name of the physical phenomenon being measured" + schema: + type: string + level: + name: level + in: query + description: | + Identification of the normative or informative relevance of the unit (Level / Category). + + - Level 1 - normative = SI normative units, standard and commonly used multiples + + NOTE: standard multiples are identified with "S" and commonly used multiples with "M" + e.g. "1 metre", "1S centimetre", "1M hectometre"). + + - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and + commonly used multiples. + + - Level 3 – informative = 9 categories of informative units (units of count and other + miscellaneous units), invariably with no comprehensive conversion factor to SI. + These units are provided for information and to facilitate the assignment and usage of + a common code value to represent such units. + - 3.1 Qualified base units from levels 1 and 2 + - 3.2 Sales units + - 3.3 Packing units + - 3.4 Shipping and transportation units + - 3.5 Industry specific units (various) + - 3.6 Information technology units + - 3.7 Integers/Numbers/Ratios + - 3.8 Multiples/Fractions/Decimals + - 3.9 Miscellaneous + schema: + type: string + commonCodeQuery: + name: commonCode + in: query + description: "This is the recommended single list of standard codes" + schema: + type: string + name: + name: name + in: query + description: "The name of the unit of measure" + schema: + type: string + description: + name: description + in: query + description: "A plain text specification of the named unit of measure" + schema: + type: string + responses: + BadRequest: + description: Bad request - Issue with parameter + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: a710a2af-4f0d-458b-8792-23fe4f736d9d + error: pagesize needs to be between 1 and 1000. + NotFound: + description: No data found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: b1f1fef1-59ad-4978-bed8-3ff96d6d3587 + error: No units of measure found + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + identifier: 0407936e-d2ad-41e9-99e2-05a5919c3075 + error: An unexpected exception occured schemas: Error: type: object @@ -353,68 +269,104 @@ components: type: string error: type: string + QuantityCategory: + type: object + properties: + groupNumber: + description: "" + type: string + sector: + description: "Name of the sector in plain english" + type: string + groupID: + description: "" + type: string + quantity: + $ref: '#/components/schemas/Quantity' + level: + $ref: '#/components/schemas/Level' + commonCode: + $ref: '#/components/schemas/CommonCode' + name: + $ref: '#/components/schemas/Name' + conversionFactor: + $ref: '#/components/schemas/ConversionFactor' + symbol: + $ref: '#/components/schemas/Symbol' + description: + $ref: '#/components/schemas/Description' UnitOfMeasure: type: object properties: commonCode: - description: | - This is the recommended single list of standard codes which is based on the following conventions. - - The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values - - - (a) alphabetic code values for units of measure as in UN/ECE - Recommendation No. 20, edition 1985; - - - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data - element number 355; - type: string + $ref: '#/components/schemas/CommonCode' name: - description: "The name of the unit of measure" - type: string + $ref: '#/components/schemas/Name' description: - description: "A plain text specification of the named unit of measure" - type: string + $ref: '#/components/schemas/Description' level: - description: | - Identification of the normative or informative relevance of the unit (Level / Category). + $ref: '#/components/schemas/Level' + symbol: + $ref: '#/components/schemas/Symbol' + conversionFactor: + $ref: '#/components/schemas/ConversionFactor' + CommonCode: + description: | + This is the recommended single list of standard codes which is based on the following conventions. - - Level 1 - normative = SI normative units, standard and commonly used multiples + The representation format for the code values shall be alphanumeric variable length 3 characters (an..3); wherever possible, existing code values are retained according to the following order of precedence for assigning values - NOTE: standard multiples are identified with "S" and commonly used multiples with "M" - e.g. "1 metre", "1S centimetre", "1M hectometre"). + - (a) alphabetic code values for units of measure as in UN/ECE + Recommendation No. 20, edition 1985; - - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and - commonly used multiples. + - (b) alphanumeric code values for units of measure as in ANSI ASC X12 data + element number 355; + type: string + ConversionFactor: + description: "The value used to convert units to the equivalent SI unit when applicable." + type: string + Description: + description: | + A plain text specification of the named unit of measure, not exceeding 350 characters in length and in English. It should be noted that such descriptions shall be progressively introduced for existing entries and where possible, shall be taken from recognized sources. All new entries having no conversion factor to SI units shall be applied to the code list with a description. A description is optional for units provided with a conversion factor. + type: string + Level: + description: | + Identification of the normative or informative relevance of the unit (Level / Category). - - Level 3 – informative = 9 categories of informative units (units of count and other - miscellaneous units), invariably with no comprehensive conversion factor to SI. - These units are provided for information and to facilitate the assignment and usage of - a common code value to represent such units. - - 3.1 Qualified base units from levels 1 and 2 - - 3.2 Sales units - - 3.3 Packing units - - 3.4 Shipping and transportation units - - 3.5 Industry specific units (various) - - 3.6 Information technology units - - 3.7 Integers/Numbers/Ratios - - 3.8 Multiples/Fractions/Decimals - - 3.9 Miscellaneous - type: string - sector: - description: "Name of the sector in plain english" - type: string - symbol: - description: "The symbol used to represent the unit of measure as in ISO 31 / 80000." - type: string - conversionFactor: - description: "Conversion factor to SI" - type: string - quantity: - description: | - The name of the physical phenomenon being measured. + - Level 1 - normative = SI normative units, standard and commonly used multiples - - (a) In levels 1 and 2 (SI or SI equivalent), the phenomena pertaining to a certain - category are listed under a heading giving the name of the relevant part in ISO 31; - - (b) In level 3 they are broken down into the 9 categories as defined below under - level/catgory. - type: string + NOTE: standard multiples are identified with "S" and commonly used multiples with "M" + e.g. "1 metre", "1S centimetre", "1M hectometre"). + + - Level 2 – normative equivalent = SI normative equivalent units (UK, US, etc.) and + commonly used multiples. + + - Level 3 – informative = 9 categories of informative units (units of count and other + miscellaneous units), invariably with no comprehensive conversion factor to SI. + These units are provided for information and to facilitate the assignment and usage of + a common code value to represent such units. + - 3.1 Qualified base units from levels 1 and 2 + - 3.2 Sales units + - 3.3 Packing units + - 3.4 Shipping and transportation units + - 3.5 Industry specific units (various) + - 3.6 Information technology units + - 3.7 Integers/Numbers/Ratios + - 3.8 Multiples/Fractions/Decimals + - 3.9 Miscellaneous + type: string + Name: + description: "The name of the unit of measure" + type: string + Symbol: + description: "The symbol used to represent the unit of measure as in ISO 31 / 80000." + type: string + Quantity: + description: | + The name of the physical phenomenon being measured. + + - (a) In levels 1 and 2 (SI or SI equivalent), the phenomena pertaining to a certain + category are listed under a heading giving the name of the relevant part in ISO 31; + - (b) In level 3 they are broken down into the 9 categories as defined below under + level/catgory. + type: string