Closed rsimoes closed 3 years ago
Thanks for raising! I think the XSD could use a clean up generally. This might be something we can get in place before publishing the 5.2 revision. That said, I'm not clear on the original reasoning around some of the XSD construction, including this Election
question. Can an XSD require certain elements and not require a strict order?
Background: https://stackoverflow.com/questions/36286056/the-difference-between-all-sequence-choice-and-group-in-xsd
One of the challenges is that many feeds which work with xs:choice
wouldn't work with xs:sequence
because sequence requires a specific order. I'm happy to make this change-over provided we do a lot of outreach to providers indicating that this could break previously-working feeds.
I would be interested in understanding the motivation for making this change. Is Election
always expected in the feed? In the NIST CDF specifications, we make certain elements required and other optional based on our use-cases. Looking at the VIP specification, it appears that all the elements under the choice are required. If this change was to be made, you would need to consider which elements should be made optional.
@JDziurlaj raises a good point. There might be use cases for VIP data that would not require an Election
element to be included. One example being a VIP formatted feed to provide only Election Administration information for States and Localities. Additionally, as elections offices adopt geo-spatial data in to their systems, there could be a use case for having the VIP feed's data structure serve as a layer of QA for implementations of geo data. Neither of these use cases would theoretically be aligned with an Election.
@JDziurlaj My motivation with the report was to get the documentation synced with the XSD. I'm not so bent on there being a required Election element and would be just as happy with it being made optional in the docs.
@rsimoes I'm now seeing what I think you're referring to. While the XSD is not requiring an Election
element, the documentation does suggest it is required: https://vip-specification.readthedocs.io/en/release/built_rst/xml/elements/election.html
The Election object represents an Election Day, which usually consists of many individual contests and/or referenda. A feed must contain exactly one Election object. All relationships in the feed (e.g., street segment to precinct to polling location) are assumed to relate only to the Election specified by this object.
Are there other examples in the documentation of this ambiguity? I'm all for removing any text that suggests the Election
element is required. I think we've identified some use cases in this thread for when an Election
should not be required in a VIP formatted feed.
@afsmythe The only other object with such wording is the Source:
The Source object represents the organization that is publishing the information. This object is the only required object in the feed file, and only one source object is allowed to be present.
The XSD also has a minimum and maximum of one for both Election
and Source
, but their placement under the unbounded choice
element renders that inert.
Proposing we punt on this until we can find a good solution for the XSD where it can specify required objects but without a specified order. This issue has raised some awareness around what use cases a VIP feed can serve, e.g. when an Election
object is not really necessary. But, the Source
object feels like a field which should be required in order to describe the source of the feed. Currently, both Election
and Source
are described similarly in the XSD. Can we leave this as-is for now?
To my knowledge there are no VIP formatted feeds which are being provided without Election
objects. So, the documentation as it stands fits with those implementations. Having a more accurate XSD and a summary of use cases for VIP feeds would be a nice-to-have feature for future versions of the documentation so I propose we move towards that goal.
In an effort to either close this issue or update the XSD, it seems we have an option to either leave the XSD as-is or make the following change to the XSD spec.
Election
, Source
and State
from the <xs:choice>
section and placing underneath VipObject
thereby making them required for each VIP feed.I suspect this would also require a specific sequence, but if these objects are considered a requirement for a VIP feed, the XSD should match.
I'm in favor of leaving the XSD as-is. I can foresee both of the use cases that @afsmythe mentioned being used in the near future - a VIP feed to solely capture LEO/SEO data or precinct shapes. The specification has a lot of utility for modeling election information, so in my opinion it should be flexible to be repurposed for various use cases.
An alternative that is worth considering is using a combination of documentation and external validation to enforce required information. Along the lines of what @JDziurlaj mentioned which NIST CDF supports, there could be a few enumerated types of VIP feeds. If we had an external VIP feed validator like the Google CDF validator, we could rely on the validator to enforce constraints that are specific to a type of feed.
Closing this and will refer in https://github.com/votinginfoproject/vip-specification/issues/413
... At least according to xmllint, that is. It seems to be due to VipObject's
<xs:choice maxOccurs="unbounded">
causing Election'sminOccurs="1"
attribute to be ignored. Removing the unbounded value triggers enforcement but also has the side effect of requiring a strict order of VipObject's child elements.