Mechanism for hackathon discoverability

[gonzalocasas]

In the context of the hackathon-in-a-box idea, a core requirement is to have discoverability of at least two main things related to a hackathon:

• Event details
• Hackathon projects

Discoverability implies machine-readable formats and standardized access patterns. Dribdat already tracks projects and a significant part of the event details, so this information needs to be exposed, but in a standard way to allow others to implement it without the need to run dribdat. The two parts (Event details and Hackathon projects) have potentially different implementations, and conceptual differences, so I will describe them separately.

Event details

Conceptually, this would be a mechanism similar to schema.org, robots.txt, or micro-format specification, to describe the hackathon's metadata in a machine-readable way and with a focus on machine discoverability as well.

Schema.org has a format for generic events, and some sub-classing for specific event types, but none of them fits exactly a hackathon: http://schema.org/Event.

On the other hand, the simplicity of a root-level file descriptor (i.e. robots.txt, humans.txt, etc) is extremely appealing.

So the proposal would be to define a root-level hackathon.json file containing the following (tentative) metadata about the hackathon:

• event name
• event date(s)
• event location(s)
• topics
• sibling events: list of links to other domains containing hackathon.json descriptors to enable event chaining)
• projects API: link to a json API to access projects presented at the hackathon (the API would be integral part of dribdat, but at the same time, should be a well-defined standard that other platforms can implement. See next section)

The sibling event link list creates a crawlable graph that connects events to each other, fostering discoverability in general, and also establishing a relations between events.

This root-level file descriptor should be placed at the event's main website's root.

Hackathon projects

A second level of detail in the meta-description of an event is its actual content, i.e. the projects presented during the event. For this, Dribdat already hosts all the information required, and the only additional need to be to expose it over a well-defined JSON end-point and format/spec.

As mentioned in the previous section, this end-point would be linked from the root-level file descriptor through the projects API property.

---

In combination these two metadata end-points would allow an event/hackathon to self-describe itself in a fully decentralized manner while allowing the creation of a graph of events to keep things tied together (for a multitude or reasons: forked events, friend events, topical events, etc).

On top of it, additional tools and services (also decentralized) could be created by crawling and visualizing the event graph in various ways. For instance, this community event calendar could be generated out of this data.

[loleg]

Note: this is related to some work on an API-first redesign of the platform earlier this year.

[loleg]

I guess the projects (teams) should be listed under performer category? To be continued..

[gonzalocasas]

@loleg I implemented also parts of the Event Schema thing on the website side of things: https://github.com/open-network-infrastructure/hugo-hackatheme/blob/master/layouts/partials/meta/schema.html
Is there a way we could share the implementation?

[loleg]

@gonzalocasas that's great! Probably using the separate repo to specify and develop the Event Schema would make sense. See also the schema for Hackathon-Hackers events aggregation, as well as the HackClub directory for examples of what people look for.

[gonzalocasas]

This schema might also be related/interesting https://schema.org/Dataset

[loleg]

Interesting example of someone going the other route - writing a scraper to aggregate hackathon results: https://github.com/andrew-m-h/HackanationGovhack

[loleg]

Another interesting example is the civic.json file used by @codeforamerica - which they suggest adding to repos as follows:

Merge this to add a civic.json file to your project. This little bit of metadata will make your project easier to search for at https://www.codeforamerica.org/brigade/projects and elsewhere. You can read more about the status attribute at https://www.codeforamerica.org/brigade/projects/stages.

[loleg]

Additional inspiration, from earlier discussions: https://spaceapi.io/
Also, we at one point did some work on an OpenAPI spec (Swagger)

[loleg]

The basic mechanism has been in place for a while, but to close this issue, we need to have a clear and accepted validation. In my mind, this is the "community calendar" mentioned in the top posted, generated from a federated list of dribdat instances.

I would also appreciate seeing at least one "static" hackathon.json involved in such this, not coming out of an app, at some point. Any updates from your side @gonzalocasas are welcome.

[loleg]

Recent discussions and experiments around #325 make me think: wouldn't it be cool if dribdat instances federated each other automatically, rather than the manual import and export of Data Packages that I have to do now?

[gonzalocasas]

It would be amazing!