betanyc / civic.json Goto Github PK

Hi, not exactly sure what you envision the scope of civic.json to be so I'm not 100% sure this is valid feedback.

I think this is a good goal:
"In theory, if civic technology groups adopt this standard, it will be possible to aggregate nationwide, regional, or topic-specific lists of civic tech projects."

But my main concern is that it's tied to having your project in a github repo, it seems like if the standard allowed for fields like name, url, organization, description it would be able to support a wider variety of project across any sort of site.

For example say BetaNYC has a hackathon coming up and they need specific types volunteers, a location and sponsors, in addition to that they would like the url to point to the meetup.com page for the event, can this standard represent that project? Is that outside of the scope of what is trying to be accomplished here?

What if my group just decided to use bitbucket instead of github for some reason?

Some of the github data seems more like metadata Forks, Watchers, Issues these may or may not exist depending on the project.

I'm concerned about the designation of "alpha" and "beta" status.

1. It's not clear exactly what characteristics should distinguish ideation vs alpha vs beta.
2. The phrases "alpha" and "beta" are such terms of art that I'm not sure they are readily meaningful.

I'd propose replacing "alpha" with some other term (maybe "in development"), with distinctions:

• Ideation - demonstration project, not fully operational
• In Development - for developer review, not suitable for general public use
• Beta - for development and public testing, possibly unstable, feedback invited

What a cool idea! We're going to add this to our projects.

Code4Maine/beehve#43

I am thinking about user-driven app-catalogs like http://dataforgood.co/ that could parse the civic.json when a project is added via it's website url to display additional information if present. An example location would be http://adoptahydrant.org/civic.json (there is nothing there - don't even click!).

@stvnrlly (Code for DC co-captain) and I (civic tech fellow in DC government) have been working on an reworking of civic.json. The idea behind it is that existing spec is:

1. Geared toward projects created outside of government (politicalEntity is not the creator)
2. Is not comprehensive enough that it could be hosted elsewhere (i.e. a registry) and made more easily discoverable
3. Certain other fields, like license and repository, would help with reuse and are required in other package standards (e.g. package.json and setup.py)

Our proposed schema is here: https://github.com/DCgov/civic.json/blob/master/schema.json
With a builder and validator here: http://open.dc.gov/civic.json/

JSON files filled out according to this schema are backwards compatible with BetaNYC's civic.json standard in that all of your required fields are also required in all (with the same naming).

I see #14 is still open, but wondering at your thoughts @chriswhong, @seanluciotolentino, and others on a PR?

The status description says:

• "Production" - Finished Product, development ongoing
• "Archival" - Finished Product, development ongoing

I wonder if that's an error. Should "archival" be "development suspended"? If not, what's the difference between the two?

Coming from reading #8 I would like to add an idea:

I would really like to have indicators of impact as optional fields. One of the reasons is having a nudge (see http://en.wikipedia.org/wiki/Nudge_theory) for people to think about impact - at least when they are adding a civic.json. We often build toys and let them die. Thinking about impact and how to measure it lets us see more clearly what we want to achieve.
But there are other reasons: Most of our work is done by volunteers so resources are scarce. We should focus on things that work. Wie only know what works if we measure and learn. Like in build, measure, learn. Also potential funders are interested in impact. They have a hard time working with anecdotes. They want facts. Having this data in the civic.json app-catalogs like http://www.civicexchange.eu/ could give additional relevant information and draw interesting comparisons between apps.

But here comes the tricky part: What is impact? For some projects it might be simply reach. So page views, media coverage and social media shares might be interesting metrics. For apps monthly active users could be a relevant metric. Growth rates might be interesting, too. This all becomes pretty fuzzy soon. But we need some standardization in order to keep things comparable. I don't have a definitive solution for this - I would like to discuss. Maybe I am the only one who thinks, this is a good idea? I'd like to hear your opinion, especially from @pmackay.

Github serves their API responses with a content-type of application/vnd.github.v3+json.

We could define a content type to help clients parse Civic JSON, especially as the format evolves. I suggest recommending in the docs that people use a defined media type when serving this, such as application/vnd.betanyc.civic+json.

Where else are civic.json discussions happening? What's the best course of action for actually adopting some of these proposed ideas? Who makes that call? Do we hold a convention?

Naming conventions on github usually include all lower case or are full of dashes. Perhaps we should include a display name field so projects can have a scree-pretty title.

1. Why are needs and categories arrays of objects? Why not simply use arrays of strings like "categories": ["Community", "Education"]. The current proposal is unnecessarily complicated by using objects.
2. It is not immediately obvious what bornAt means. I would use a term that is not metaphorical. The PROV ontology has wasGeneratedBy. If you prefer, originatingEvent would be the most literal.
3. politicalEntity is too narrow. What if I make an app for an NGO? Why not just use the term targetOrganization, which is agnostic to whether the organization is political or not?

If you want to reuse terms from existing vocabularies:

1. Instead of thumbnailUrl, use image from Schema.org.
2. Instead of geography, use geographicArea from Schema.org.
3. Instead of categories or topic, use the singular category from Description of a Project, used by Python, Mozilla, Freshmeat, etc. Alternatively, use subject, from DCMI, the most widespread metadata standard.

Subtasks:

• update readme to be “done”
• Add more to needs example: Designer, developer, data scientist, subject matter experts, project manager, community testing, deployment support

The meta question: Is there a certain process for adding new fields to the civic.json standard?

Code for DC is hoping to change to a civic.json powered projects page, but they have some fields that they want to include that aren't described by the current spec. Here is the civic.json file I built for one of their projects, using data from the Code for DC projects page.

The fields I added that aren't on the standard are below:

{
"contact": [
    {
      "name": "Marcus Louie",
      "email": "",
      "twitter": "@mlouie"
    }
  ],
  "communityPartner": "Bread for City",
  "moreInfoLink": "https://hackpad.com/Code-for-DC-District-Housing-KlQ2UbX0Imc"
}

I'm sure there are other fields that civic hackers will want to include as this standard develops, so I was hoping to start a conversation about what this process will look like.

This field would allow the repo owner to specify a number of other projects that are related to the project with the civic.json file. This would allow any aggregator to visualize a network of projects and evaluate their influence within the civic tech ecosystem.

i would like to write more about Linked Data and taking advantage of modeling captured in ontologies like http://www.lexicater.co.uk/vocabularies/innovation/ns.html#

JSON-LD spec: http://www.w3.org/TR/json-ld/

see more

• basic: http://schema.org
• advanced: http://lov.okfn.org