icss style guide

icss -- ICSS Style Guide

This is the collection of datasets and types from the infochimps data catalog

ICSS Style Guide:

• Data sets' namespace should be: category.subcategory.source -- eg. geo.location.foursquare
• Wherever possible, the data set name should be the pluralized name of the most applicable type -- eg. places, ufo_sightings
• Path to the file should match the namespace; the file name should match the data set name
• The response name should be chosen independently. They will often, but not necessarily, live near or in the same namespace as their data set: encyclopedic.wikipedia.wikipedia_article is returned by encyclopedic.wikipedia.dbpedia.wikipedia_articles
• You may put non-core types directly in the dataset's ICSS file (but use a fully-qualified name if the namespaces don't match)
• Write a good, multi-paragraph doc string or check in with the person who will author it.
• Are there messages present?
• The first line of a property's doc string (field's doc string) MUST be < 50 characters
  • the remainder should be fully descriptive. One additional sentence is plenty.
• Be sure that structured types, map, array, etc, are sub-hashes (indented):
  • good: :type: { :type: 'array', :items: 'string' }
  • bad: :type: 'array', :items: 'string'

Naming a Dataset or Type

• domain -- cat/subcat, eg sports/baseball
• source -- the source slug: a short unique name for this provider
• data set name -- a unique slug for this dataset, often but not always the pluralized name of the response type: wikipedia_articles or topline.
• action -- the request to execute: search, show, list, etc

Request

• Request name should be 'params'
• Request type should be bare (so it is namespaced)

Geolocator queries

Query params:

• f.{whatever} -- filter

• g.{whatever} -- geolocator anchor

• lim.{whatever} -- limiter

• l -- layer

• out.

  • shape -- data structure
  • callback -- json-p
  • pretty -- pretty-print
  • wrapper -- html

     wrapper

• meta.{whatever} -- meta-control (error, etc)

• vers.{whatever} -- versioning

• apikey -- authentication

• format is implied by normal HTTP accepts &/or extension but goliath figures that out

Doc style

• The first line of a property's doc string (field's doc string) MUST be < 50 characters

• Include a period at the end of the doc.

Actions (verbs)

• search (not search_nearby)
• show (not direct_lookup)
• list (contents by tile_id) (intersects is a special dataset, list is its verb)

Utility / Primitive calls:

• geo/utils ... geolocate is the verb

---

Other

md5id

Digest::MD5.hexdigest("#{domain_slug}:#{domain_id}")

Relationships

• Relationships should have explicit valence or explicit symmetry. That is, same_as is always symmetric. hyperlinks_to and follows
• reading the type name as " REL's " should make the directionality clear: