Population object in fhir schema

Inside the MedicinalProductContraindication Resource, the data-type or Resource “Population” is referenced at
“population” : [{ Population }] // The population group to which this applies

However stated at the top of the page, " > This type is still undergoing development and review by the appropriate Workgroups. At this time, is considered only as a draft design not suitable for production implementation"

This is also currently defined in the json schema found at http://www.hl7.org/fhir/downloads.html but does not contain this same disclaimer.

I have several questions regarding this type of situation.
1.) In the json schema mentioned above, there is no indication of whether or not these Resources or objects such as Population are in the “draft stage” or not, am I missing something or is there no way to determine this other than manually looking at the statuses at https://www.hl7.org/fhir/resourcelist.html ?
2.) If placeholders for these “draft” resources were to be implemented, what kind of object can I expect Population to be, Resource or Data-Type?
3.) In the JSON mentioned above, in definitions.ResourceList.oneOf you can find a list of all Resources, but as far as I can tell there is no similar list for Data Types, nor is Population included in this, but MedicinalProductContraindication is, even though it is in “draft” stage. It seems to be a sort of inconsistent handling of these definitions so I am not sure how to handle the information contained in that json schema due to observations like this. It seems like additional information in the JSON might be useful to clear up this kind of confusion.
Any clarifications on the points above would be greatly appreciated.

  1. The resource is draft and all artifacts derived from the artifact definition are also draft. The expectation is that all implementers will look at the spec to understand the status and intended use
  2. As Population is currently defined, it’s a data type
  3. It’s not a formally approved data type, so isn’t in the usual lists. It should be in the profiles-types.json file though which lists all data types from the R4 specification

Thanks lloyd I appreciate the help. In regards to question 1, although I have been referencing and reviewing the fhir docs, I was hoping that the json schema would be the complete source of truth per version, so I can programmatically define resources without having to manually check each resource doc, if that makes sense.

JSON schema isn’t capable of expressing a lot of the rules. For example, it can’t describe (or enforce) vocabulary bindings, can’t express a lot of the FHIRPath constraints, has no notion of mustSupport (as distinct from cardinality), etc. JSON schema is useful for performing partial validation and for tools that support authoring example instances using JSON, but to understand the complete specification, you’ll need to look beyond the schema.

The downloadable schema does not need to express the rules but, in my opinion, it should be an exact representation of that current version’s resource definitions because isn’t that the point of a schema? If an item is in draft, aka a work-in-progress, it does not make sense to include it in the schema file, since that schema is saying these are the defined structures for the R4 version of the implementation. Draft items can still be found in the spec or other places, but having them in the schema as if they are part of that version’s resource adds confusion to an already complex process of implementing FHIR.

If the draft items are always going to be apart of the schema file then would it make sense to add a key to indicate the draft status?

The vast majority of the FHIR specification is some level of draft - only a few resources are now locked down as “normative”. The bulk are considered “Standard for Trial Use” and about 20% are draft. Because all resources are interlinked it’s not possible to publish some without publishing all. We could chose to put large volumes of documentation into the schemas that cover everything that’s in the HTML, but that would increase their memory consumption by 400% or more. Given that the primary purpose of the schemas is for computable validation, not human review, it seemed more appropriate to keep the schemas (for computers) light-weight and put the full documentation in the HTML (for humans). That decision has been reaffirmed by the majority of implementers when presented with the choice to inject more documentation into the schemas.

I totally understand that the spec is mostly some level of draft.

It would be nice if the fully documented schema was an option where the implementers could chose the lightweight or full version of the schemas when downloading/ using. I’m not sure I see what you are saying with the memory consumption, it doesn’t seem like a 20MB file would be that big of a deal, especially if it was able to aid in development efforts. If everyone has to cross reference specs and schema files, it would not surprise me if you end up with many different ‘flavors’ of fhir implemented.

Just a thought, do you think a more verbose schema file would not be helpful strictly because of the memory consumption of reading a large file? Could it be multiple files that interlock? I feel that developers working on fhir implementation would prefer and benefit from having a verbose schema available.

You’d be looking at around 40MB which is a pretty good chunk for mobile devices. That doesn’t mean we couldn’t provide a heavily documented json schema if there was a demand. Thus far, there hasn’t been a whole lot of interest from the implementer community in doing that. Feel free to use the “propose a change” link and/or socialize this notion on chat.fhir.org and we can look at it as a possibility for R5.

It would be a solid chunk for mobile, but I doubt anyone would be trying to deliver it client-side. I particularly am looking to use it for development purposes and fhir resource validating. I will definitely check out the ‘propose a chain’ and again, thanks for the help @lloyd!