Where in a BibJSON collection should metadata go?

As first object in a list of objects

Similar to bibtex, collection metadata could be the first object in a list of objects. However, this presents problems:

• The metadata is not a record like all other records – it looks different, and does not really sit well in a result list.
• When viewing a collection, results are shown based on the search parameters provided (or the default ones) – so the first record is not always on display.
• When requesting a result list as JSON, there may therefore be no metadata.
• Prepending a metadata object to any given result list will make the content at a particular URL different depending on the format it is viewed in.
• Counts of results start to get confusing if the metadata is considered a record in its’ own right – the count when viewed in HTML will not match the count in JSON, and iterating over all objects in the count would either mismatch the count if it does not include the metadata object, or include an undesired read of the metadata object if it is.
• When going to the URL of a particular record, there will be no collection metadata. But we would still expect the returned BibJSON to follow the same structure – so a collection metadata object would be expected based on convention, but not present or relevant.

As keys in an encompassing object

Alternatively, metadata could be provided as keys in a JSON object, with records provided as a list pointed at by a “records” key. This avoids the problems listed above, but moves away from the simple bibtex style of having the metadata as first object in a list. However in solving the problems listed above, it is probably still simpler overall.

Proposing the solution

I propose providing the metadata as keys, and providing the returned records as a list identified by the “records” key. Future alterations for providing person records will also fit nicely, being dropped in as a list identified by a “persons” key, or similar.

Therefore, viewing a collection such as http://bibsoup.net/collection/pitman.json as JSON should return something like the following:

{
  "received": "2011-09-25 15:09:00.992915",
  "format": "bibtex",
  "collection": "pitman",
  "source": "http://stat.berkeley.edu/~pitman/bibserver.bib",
  "size": 10,
  "from": 0,
  "query": "http://bibsoup.net/collection/pitman.json",
  "records": [
    {
        "bibnumber": "3",
        "publisher": "Jerusalem Academic Press",
        "booktitle": "Studies in Probability and Statistics",
        "author": [
            "Pitman, J W"
        ],
        "mrclass": "60J05 (60G40 60G17 60K15)",
        "collection": "pitman",
        "pages": "41 to 57",
        "citekey": "p74a",
        "mrnumber": "MR0431384",
        "year": "1974",
        "keywords": [
            "Stopping time",
            "Identities",
            "Markov chain",
            "Occupation time"
        ],
        "title": "An identity for stopping times of a Markov Process",
        "type": "incollection",
        "id": "f54567c6191443cda2d3a81cce6def90"
    },
    ...(+ 9 more records)...
  ]
}