0006: Bill feedback

[jpmckinney]

Consistency:

• Why not use organization to match other schema, instead of from_organization?
• Would it be consistent with other parts of the schema to rename entity_type to _type?

Choice of terms:

• mimetype is old-fashioned. This is typically called a content_type for some time.
• versions.links and documents.links: These refer to different forms of the version/document. DCAT uses the term distributions. Whatever term you decide on, DCAT's definition of Distribution is very clear and can maybe be reused. Strictly speaking, links don't have a content type, but distributions do.
• versions.name and documents.name: Based on the examples, these are not really the names/titles of the documents - maybe note is closer to the intended meaning?
• For summaries and other_titles, it's not clear why the property name is text. I would either expect value (as in ContactDetail, Count, and most future Popolo subdocuments) or the singular form (as in Identifier, OtherName) - in this case summary or title.

Here are some suggested terms from the Dublin Core Metadata Terms, which Popolo is likely to adopt in a generic Document class, since they are the most broadly used metadata terms:

• identifier instead of name, since HB 2117 is better described as an identifier than as a name. The docs already acknowledge that name is easily confused with title.
• abstract or abstracts instead of summaries

Questions:

• Isn't primary a classification?
• "The type of the version" and "The type of the document": Could you provide example values?
• is actions.text a description of the action ("Referred to committee"), or the actual text of the action which may be identical to the text of a motion ("That Bill HB-1 be referred to the Committee on House Adminstration"), or both? text suggests that the action text is taken from official proceedings, but the definition of the term suggests it's a description of the action, not its official text. Depending on the most common case, it may be clearer to name it description.

[jamesturk]

thanks for this!

• from_organization - I'm torn on this one too, I think @paultag suggested it(?) because there are many kinds of organizations associated with a bill, and this clarifies what relationship we're looking for here. I'd be OK with changing it to organization though and relying on documentation to clarify what belongs there.
• generally we treat underscore fields as private (not exposed via the API), is this to bring it in line with something else in particular?
• noted on the mimetype thing, I had the same thought. I think we'll change it.
• re: versions & documents - good points on both fronts, I'll look into a change
• yeah, 'text' didn't seem right to me either. using the singular like other_names and identifiers does is probably the right way.
• we were concerned about confusion with machine identifiers, which seems to be what identifier is used for elsewhere, wouldn't the use here be inconsistent with the use of identifiers on Person & other classes?
• abstracts seems acceptable, I'll run this by everyone
• re: primary multiple classifications might indicate that a sponsor is primary. one jurisdiction might use author & sponsor whereas another might use sponsor & cosponsor and some simply list everyone from the original chamber as a sponsor and the opposite chamber as cosponsor but the first one of each type is primary
• will add examples for types on versions/documents
• good Q about actions.text, not sure I have an answer (so it may be both). we lean towards the official text but there are times we need to clean it up because what is provided is awful (usually heavily abbreviated)

[jamesturk]

TODOs:

• [x] change or justify from_organization
• [x] change mimetype to content_type
• [x] update definition of links to be in line w/ distributions
• [x] documents/versions.name should be .note?
• [x] change summaries & other_titles key from 'text' to 'value' or 'title'/'summary'
• [x] renaming summaries to abstracts?
• [x] explain why primary flag exists in OCDEP
• [x] examples for type of version/document - eliminated these in favor of type
• [x] actions.text - clarify intended data (original or summary?) rename key?

[paultag]

re: from_organization - yeah, it was to let the relationship be described a bit more clearly, since there are many relations that orgs have to bills.

Something like organization_id would be OK if that's what's needed to normalize the spec

[jpmckinney]

• I think from_organization is fine now that I understand the reasoning. It's conceivable that properties for other related organizations will be added, in which case it will be better to have from_organization.
• Actually, I got mixed up, "media type" is the official term (IANA, IETF, Wikipedia). "Content type" is commonly used because it's in HTTP.
• Understood re: primary. I wasn't sure if classification was going to normalize the various ways of attributing primary-ness, or if it was going to maintain each jurisdiction's terms ("sponsor", "author", etc.)
• Thinking about sponsors.classification, it seems to describe the person's role in sponsoring the bill, so perhaps role would be more descriptive?
• The word "sponsors" typically refers directly to the people or organizations sponsoring a bill. However, here the value of sponsors is maybe better described as a list of Sponsorship objects, which relate a bill to its sponsors. Would sponsorships be clearer than sponsors?
• identifier is used on VoteEvent to store the number or other identifier of the vote, e.g. "212" for Vote No. 212. In at least Brazil and Switzerland, vote events have human-readable titles in addition to identifiers. "HB 1227" is definitely a code of some kind, so it's appropriate to use identifier. The identifiers for people and organizations are less commonly used in public discourse, since they are more easily referenced by name.

Question:

• Is it possible to have a name without having an entity_type in sponsors or related_entities?

[jamesturk]

Implemented a lot of the changes discussed here. A few documentation clarifications to add, and one or two things left to decide. (@paultag @twneale - chiming in here would be helpful if you have a strong opinion)

• I think sponsors -> sponsorships makes sense, but then the sponsorship should have a classification not a role (role seems like it'd describe the person's role, which is confusing). Can make this change next if we're in agreement.
• Regarding actions.text - maybe this should be description or something else? We used to call it actions.action in OpenStates.

[paultag]

Yeah, I'm sold on sponsors -> sponsorships, since it's really talking about the relation, not the entity

As a result, I think this makes classification make a bit more sense, since you're talking about the sponsorship relation's classification, not the sponsor's role in the act of sponsorship

[jpmckinney]

I guess it can go either way. The Membership and Post classes use a role property to describe the role of whoever is a member / holds the post; similarly, sponsorship can describe the role of the person sponsoring. For me, words like "author" and "cosponsor" sound more like roles than classifications.

I'm trying to think of a statement I can make about a sponsorship using the words "cosponsor" and "classification". I can say "Yoda's sponsorship of HB 1 was as a cosponsor" (or more simply, "Yoda sponsored HB 1 as a cosponsor"), or I can ask "What was Yoda's role in sponsoring HB 1?" but saying "Yoda's sponsorship of HB 1 was classified as a cosponsorship" or asking "How was Yoda's sponsorship of HB 1 classified?" seem more clumsy; I also had to switch "cosponsor" to "consponsorship".

Anyway, no strong opinion here, but Membership is an example of a person relating to another entity where role made sense.

[jamesturk]

I think either could work here, and yes trying to use classification is a bit clunky, but it is consistent with how we tend to treat the classification term elsewhere (namely, a different set of options per appearance) and has less confusion with membership.role.

Other than that, I think I've made all discussed changes, on to votes!

[jpmckinney]

Awesome, you can @ mention me in the Vote issue.

One last question that got lost earlier: is it possible to have a name without having an entity_type in sponsors or related_entities? If they always both occur, I may have a change to suggest.

[jamesturk]

Ah- Ideally no, but practically yes.

If we're scraping data and there's a list of sponsors we might get something ambiguous- 'Boss Ribs' - we don't know if that is the Boss Ribs Committee or Ms. Boss Ribs ( http://openstates.org/mt/legislators/MTL000177/forrestina-frosty-calf-boss-ribs/ )

So entity_type can be blank until it is resolved to a specific entity.

On Wed, Jun 18, 2014 at 11:56 AM, James McKinney notifications@github.com wrote:

Awesome, you can @ mention me in the Vote issue.

One last question that got lost earlier: is it possible to have a name without having an entity_type in sponsors or related_entities? If they always both occur, I may have a change to suggest.

— Reply to this email directly or view it on GitHub https://github.com/opencivicdata/docs.opencivicdata.org/issues/19#issuecomment-46455250 .

[jpmckinney]

Thanks for the clarification. The spec has all properties after actions as subproperties of actions - is there an indentation error?

[jamesturk]

ah yes, just saw & fixed this!

ok closing this one out for now