How to correctly populate BiomedicalConceptProperty values

[pendingintent]

I am unsure how to populate the BiomedicalConceptProperty attributes. Specifically, I do not know from where the standardCode value originates. I am using the API to retrieve values for a dataset specialization associated with a particular BC. For example:
BC title: "Absolute Basophil Count"
BC code: C64470

Now retrieve the associated DSS values for this BC using the code:
https://api.library.cdisc.org/api/cosmos/v2/mdr/specializations/datasetspecializations?biomedicalconcept=C64470

this returns the API HREF: /mdr/specializations/sdtm/datasetspecializations/BASOBLD

Send a request to the DSS API HREF: https://api.library.cdisc.org/api/cosmos/v2/mdr/specializations/sdtm/datasetspecializations/BASOBLD

response:

    "_links": {
        "parentBiomedicalConcept": {
            "href": "/mdr/bc/biomedicalconcepts/C64470",
            "title": "Absolute Basophil Count",
            "type": "Biomedical Concept"
        },
        "parentPackage": {
            "href": "/mdr/specializations/sdtm/packages/2025-12-16/datasetspecializations",
            "title": "SDTM Dataset Specialization Package Effective 2025-12-16",
            "type": "SDTM Dataset Specialization Package"
        },
        "self": {
            "href": "/mdr/specializations/sdtm/datasetspecializations/BASOBLD",
            "title": "Basophil Count in Blood",
            "type": "SDTM Dataset Specialization"
        }
    },
    "datasetSpecializationId": "BASOBLD",
    "domain": "LB",
    "shortName": "Basophil Count in Blood",
    "source": "LB.LBTESTCD",
    "sdtmigStartVersion": "3-2",
    "sdtmigEndVersion": "",
    "variables": [
        {
            "name": "LBTESTCD",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C65047",
                "submissionValue": "LBTESTCD",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C65047"
            },
            "assignedTerm": {
                "conceptId": "C64470",
                "value": "BASO"
            },
            "role": "Topic",
            "relationship": {
                "subject": "LBTESTCD",
                "linkingPhrase": "is the code for the value in",
                "predicateTerm": "IS_DECODED_BY",
                "object": "LBTEST"
            },
            "mandatoryVariable": true,
            "mandatoryValue": true,
            "comparator": "EQ"
        },
        {
            "name": "LBTEST",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C67154",
                "submissionValue": "LBTEST",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C67154"
            },
            "assignedTerm": {
                "conceptId": "C64470",
                "value": "Basophils"
            },
            "role": "Qualifier",
            "relationship": {
                "subject": "LBTEST",
                "linkingPhrase": "decodes the value in",
                "predicateTerm": "DECODES",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": true
        },
        {
            "name": "LBCAT",
            "isNonStandard": false,
            "assignedTerm": {
                "value": "HEMATOLOGY"
            },
            "role": "Qualifier",
            "relationship": {
                "subject": "LBCAT",
                "linkingPhrase": "groups values in",
                "predicateTerm": "GROUPS",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false
        },
        {
            "name": "LBORRES",
            "dataElementConceptId": "C70856",
            "isNonStandard": false,
            "role": "Qualifier",
            "dataType": "float",
            "length": 12,
            "format": "12.4",
            "significantDigits": 4,
            "relationship": {
                "subject": "LBORRES",
                "linkingPhrase": "is the result of the test in",
                "predicateTerm": "IS_RESULT_OF",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "originType": "Collected",
            "originSource": "Vendor",
            "vlmTarget": true
        },
        {
            "name": "LBORRESU",
            "dataElementConceptId": "C67391",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C71620",
                "submissionValue": "UNIT",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C71620"
            },
            "valueList": [
                "10^9/L",
                "10^6/L"
            ],
            "role": "Qualifier",
            "relationship": {
                "subject": "LBORRESU",
                "linkingPhrase": "is the unit for the value in",
                "predicateTerm": "IS_UNIT_FOR",
                "object": "LBORRES"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "vlmTarget": true
        },
        {
            "name": "LBSTRESC",
            "dataElementConceptId": "C70856",
            "isNonStandard": false,
            "role": "Qualifier",
            "dataType": "float",
            "length": 12,
            "format": "12.4",
            "significantDigits": 4,
            "relationship": {
                "subject": "LBSTRESC",
                "linkingPhrase": "is the result of the test in",
                "predicateTerm": "IS_RESULT_OF",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "originType": "Collected",
            "originSource": "Vendor",
            "vlmTarget": true
        },
        {
            "name": "LBSTRESN",
            "dataElementConceptId": "C70856",
            "isNonStandard": false,
            "role": "Qualifier",
            "dataType": "float",
            "length": 12,
            "format": "12.4",
            "significantDigits": 4,
            "relationship": {
                "subject": "LBSTRESN",
                "linkingPhrase": "is the result of the test in",
                "predicateTerm": "IS_RESULT_OF",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "originType": "Collected",
            "originSource": "Vendor",
            "vlmTarget": true
        },
        {
            "name": "LBSTRESU",
            "dataElementConceptId": "C67391",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C71620",
                "submissionValue": "UNIT",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C71620"
            },
            "assignedTerm": {
                "conceptId": "C67255",
                "value": "10^9/L"
            },
            "role": "Qualifier",
            "relationship": {
                "subject": "LBSTRESU",
                "linkingPhrase": "is the unit for the value in",
                "predicateTerm": "IS_UNIT_FOR",
                "object": "LBSTRESN"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "vlmTarget": true
        },
        {
            "name": "LBLOINC",
            "isNonStandard": false,
            "assignedTerm": {
                "value": "26444-0"
            },
            "role": "Qualifier",
            "relationship": {
                "subject": "LBLOINC",
                "linkingPhrase": "identifies an observation described by",
                "predicateTerm": "IDENTIFIES_OBSERVATION",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": false,
            "mandatoryValue": false
        },
        {
            "name": "LBSPEC",
            "dataElementConceptId": "C70713",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C78734",
                "submissionValue": "SPECTYPE",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C78734"
            },
            "assignedTerm": {
                "conceptId": "C12434",
                "value": "BLOOD"
            },
            "role": "Qualifier",
            "relationship": {
                "subject": "LBSPEC",
                "linkingPhrase": "is the specimen tested in",
                "predicateTerm": "IS_SPECIMEN_TESTED_IN",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false,
            "comparator": "EQ"
        },
        {
            "name": "LBFAST",
            "dataElementConceptId": "C93566",
            "isNonStandard": false,
            "codelist": {
                "conceptId": "C66742",
                "submissionValue": "NY",
                "href": "https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/C66742"
            },
            "subsetCodelist": "NY_NY",
            "valueList": [
                "N",
                "Y"
            ],
            "role": "Qualifier",
            "relationship": {
                "subject": "LBFAST",
                "linkingPhrase": "is the subject's fasting status during the performance of the test in",
                "predicateTerm": "IS_SUBJECT_STATE_FOR",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": false,
            "mandatoryValue": false
        },
        {
            "name": "LBDTC",
            "dataElementConceptId": "C82515",
            "isNonStandard": false,
            "role": "Timing",
            "relationship": {
                "subject": "LBDTC",
                "linkingPhrase": "is the date of occurrence for",
                "predicateTerm": "IS_TIMING_FOR",
                "object": "LBTESTCD"
            },
            "mandatoryVariable": true,
            "mandatoryValue": false
        }
    ]
}```

Now iterate over the variables to identify the properties associated with the BC.

variables: ['LBTESTCD', 'LBTEST', 'LBCAT', 'LBORRES', 'LBORRESU', 'LBSTRESC', 'LBSTRESN', 'LBSTRESU', 'LBLOINC', 'LBSPEC' , 'LBFAST', 'LBDTC']

I am storing the "dataElementConceptId" attribute value as the code/standardCode in the `code` database.

However, there is not always a "dataElementConceptId" attribute defined.  This leads to code values missing in the 
USDM JSON file that is generated.

[generate_usdm.json](https://github.com/user-attachments/files/25799059/generate_usdm.json)

Is this the correct value to use or should I be using the `codelist/conceptId` attribute defined for each property?

[pendingintent]

Search for "BiomedicalConcept_67" in the attached JSON to see what I am reporting.
generate_usdm.json

[BSnoeijerCD]

@pendingintent
I have seen this 'problem' as well indeed. As we wanted the BC's to be flexible, we can always add properties.
If a data element concept is only in the specializations and not in the conceptual layer then you will typically not have a dec_id which probably makes sense. So then you could treat it as an extension. However, these sdtm variables have a NCIt code for the SDTM which could be used instead:

• LBTEST: C117142
• LBTESTCD: C83322
• etc

Unfortunately that is not stored in the specializations.

Note that the LBLOINC actually is expected to be stored as an alias code on the Biomedical concept level and not as a property. In that way we can also add other codes (from laboratories for example) as needed.

[pendingintent]

How can LBLOINC be fixed? Dataset Specializations are automatically mapped in the workbench through the associated BC.
code: C64470
title: "Absolute Basophil Count"

https://api.library.cdisc.org/api/cosmos/v2/mdr/bc/biomedicalconcepts/C64470
->
https://api.library.cdisc.org/api/cosmos/v2/mdr/specializations/datasetspecializations?biomedicalconcept=C64470 (returns DSS API endpoint)
->
https://api.library.cdisc.org/api/cosmos/v2/mdr/specializations/sdtm/datasetspecializations/BASOBLD

Are there any rules available that explain the expected mappings?

[BSnoeijerCD]

LBLOINC has always the same name I assume.
However, there are no rules available / created yet for the mappings. We could include that in the handbook. But it is good to align on this more so we are all on the same page.

[pendingintent]

We will need to determine the correct mapping rules for these cases. Otherwise, it is difficult to programmatically map these values and the CORE conformance rules will register a failure:

CORE-000427/DDF00035 - "There is not a one-to-one relationship between code and decode within a codeSytem and corresponding codeSystemVersion" -> This error occurs due to the None value in the Code attribute.

[bsnoeijer]

We will need to determine the correct mapping rules for these cases. Otherwise, it is difficult to programmatically map these values and the CORE conformance rules will register a failure:

CORE-000427/DDF00035 - "There is not a one-to-one relationship between code and decode within a codeSytem and corresponding codeSystemVersion" -> This error occurs due to the None value in the Code attribute.

Note that the rule produces an Warning (partially executable) and not an error.
For USDM, it might be good to consider to make codes for properties optional instead of required. Then we can ommit the coding in case it is not available (yet).

[pendingintent]

"properties": [
{
"id": "BiomedicalConceptProperty_9",
"name": "RSTESTCD",
"label": "RSTESTCD",
"isRequired": true,
"isEnabled": null,
"datatype": "",
"responseCodes": [],
"code": {
"id": "AliasCode_14",
"extensionAttributes": [],
"standardCode": {
"id": "Code_21",
"extensionAttributes": [],
"code": "",
"codeSystem": "/mdr/specializations/sdtm/packages/2025-12-16/datasetspecializations",
"codeSystemVersion": "2025-12-16",
"decode": "RSTESTCD",
"instanceType": "Code"
}
},
"notes": [],
"instanceType": "BiomedicalConceptProperty"
},

[lexjansen]

A few comments.

• The "reference" property ("A citation to an authoritative source for a biomedical concept.") is used to store the DSS endpoint. This feels not right, since this is not a biomedical concept reference. Also, when there are more related endpoints (Eg. CRF specializations), where will those be defined? Would it not be better to have an extension attribute for this.
• Same for the DSS variables. To me they are not biomedical concept properties. The BC data elements concepts (DEC) would be biomedical concept properties. The DSS variables could be extension properties, like in the future properties related to CRFs.

[bsnoeijer]

Totally agree with your comment @lexjansen . I was thinking along the same lines.

[pendingintent]

Thank you for this. I have some rework to do in the workbench, but this is the definitive information I needed.

[BSnoeijerCD]

@pendingintent See also the mapping document I created a while ago
BC2USDM_Map.docx

[pendingintent]

Thank you for the document, @BSnoeijerCD. This is what I needed to complete my understanding from the discussions I have had this week.