81 | HOW TO DO BIBJSON
96 |It's just JSON... only, with some useful conventions.
97 |The purpose of BibJSON
105 |BibJSON is a convention for representing bibliographic metadata in JSON; 106 | it makes it easy to share and use bibliographic metadata online.
107 |It is a form of JSON - a simple, useful and common way of representing data on the web; we use it to 108 | shift information around between our apps.
109 |When we want to share with other people, 110 | having some conventions about how to use the JSON to do so can be a very useful thing.
111 |By sharing BibJSON in an agreed manner, we can share data online and use it 112 | directly in web applications to quickly and easily make better use of our data.
113 |BibJSON is designed to be simple and useful above all else. 114 | It has virtually no requirements, and you could use your own namespaces to extend it. 115 | Use it as best fits the purpose of your community.
116 |
119 | {
120 | "title": "Open Bibliography for Science, Technology and Medicine",
121 | "author":[
122 | {"name": "Richard Jones"},
123 | {"name": "Mark MacGillivray"},
124 | {"name": "Peter Murray-Rust"},
125 | {"name": "Jim Pitman"},
126 | {"name": "Peter Sefton"},
127 | {"name": "Ben O'Steen"},
128 | {"name": "William Waites"}
129 | ],
130 | "type": "article",
131 | "year": "2011",
132 | "journal": {"name": "Journal of Cheminformatics"},
133 | "link": [{"url":"http://www.jcheminf.com/content/3/1/47"}],
134 | "identifier": [{"type":"doi","id":"10.1186/1758-2946-3-47"}]
135 | }
136 |
137 | Overview
145 |-
146 |
- A BibJSON record is a JSON object 147 |
- A BibJSON collection is a JSON object containing "metadata" followed by "records" 148 |
- The "records" key in a collection points to a list of BibJSON records (JSON objects) 149 |
- The collection and the records both have the "collection" key, and their value should be the same 150 |
- Each record should have a "cid" - an identifier unique within the parent collection 151 |
- Each record should have a "type" - such as "article", "book", or even "author" 152 |
- Record type places no constraint on what can be placed in the record 153 |
- The default set of keys are based on the 154 | bibtex keys 155 |
- BibJSON keys are lowercase, no spaces, and usually singular 156 |
- The keys can point to strings, lists, or objects 157 |
- Any thing that is a simple string should remain so 158 |
- Where object complexity is required, make it an object 159 |
- Where additional keys are namespaced, include a "namespace" declaration in the collection "metadata" 160 |
- BibJSON APIs may return other metadata relevant to the parent app; developers can identify such metadata by prefixing the key with "_"; just ignore what is not useful to you 161 |
165 | # Any simple string is just a string, e.g.
166 | "year":"2011"
167 |
168 | # Anything more complex is an object, such as
169 | "journal":{
170 | "name": "A really great journal",
171 | "id": "rgjourn"
172 | }
173 |
174 | # Anything that could have multiples goes in a list -
175 | "author":[
176 | {
177 | "name": "MacGillivray, Mark"
178 | },
179 | {
180 | "name": "Pitman, Jim"
181 | },
182 | "lists can contain string, list, and object children"
183 | ]
184 |
185 | Which things are objects
193 |As mentioned in the overview, when something is simple it can just be 194 | a string pointed at by a suitable key; but otherwise, it needs to be an 195 | object. So which things are objects?
196 |-
199 |
- author is a list of objects 200 |
- editor is a list of objects 201 |
- license is a list of objects 202 |
- identifier is a list of objects 203 |
- link is a list of objects 204 |
- journal is an object 205 |
Web links and identifying things
214 |Web links are objects in a list and can contain a URL, an anchor, and more.
215 | They should go to relevant stuff about the current record.
216 | Identifiers should identify the thing the current record is about. They
217 | must have an ID and a type, and can have more.
219 | {
220 | "title": "An example of links",
221 | "link": [
222 | {
223 | "url": "http://example.com",
224 | "anchor": "Go to Example"
225 | }
226 | ]
227 | "identifier": [
228 | {
229 | "id": "10.1186/1758-2946-3-47",
230 | "type": "DOI",
231 | "url": "http://dx.doi.org/10.1186/1758-2946-3-47"
232 | }
233 | ]
234 | }
235 |
236 | author, editor, journal
239 |Some typical keys for these objects
240 |
241 | {
242 | "author": [
243 | {
244 | "name": "Erdös, Paul",
245 | "alternate": ["Paul Erdos"],
246 | "firstname": "Paul",
247 | "lastname": "Erdös",
248 | "id": "paulerdos"
249 | }
250 | ],
251 | "editor": [
252 | # as above...
253 | ],
254 | "journal": {
255 | "name": "American Journal of Mathematics",
256 | "shortcode": "Amer. J. Math.",
257 | "id": "amerjmath"
258 | }
259 |
260 | You could even have these as separate records in a collection, 261 | (use the "type" field to identify "author", say) 262 | then refer to them from other objects by their ID.
263 |Licensing things
271 |License information is represented by the "license" key. It should 272 | contain a type and a URL to an explanation of the license. It could 273 | also contain other fields giving more info about the license, 274 | if necessary. License is a list, just in case there are multiples...
275 |(We have chosen to Americanise ourselves and use "license" :)
276 |Learn more about bibliographic metadata licensing at 277 | http://openbiblio.net/principles
278 |
281 | {
282 | "license": [
283 | {
284 | "type": "copyheart",
285 | "url": "http://copyheart.org/manifesto/",
286 | "description": "A great license",
287 | "jurisdiction": "universal"
288 | }
289 | ]
290 | }
291 |
292 | collection
300 |
301 | # an example collection
302 | {
303 | "metadata": {
304 | "collection": "my_collection",
305 | "label": "My collection of records",
306 | "description" "a great collection",
307 | "id": "long_complex_uuid",
308 | "owner": "test",
309 | "created": "2011-10-31T16:05:23.055882",
310 | "modified": "2011-10-31T16:05:23.055882",
311 | "source": "http://webaddress.com/collection.bib",
312 | "records": 1594,
313 | "from": 0,
314 | "size": 2,
315 | },
316 | "records": [
317 | {
318 | "collection": "my_collection",
319 | "type": "book",
320 | "title": "a great book",
321 | "id": "your_record_id",
322 | ...
323 | },
324 | ...
325 | ]
326 | }
327 |
328 | NOTE: You can provide your own record IDs in the "id" key. Internal IDs allocated 329 | by BibServer (and other internal data set by BibServer or other processes) are 330 | set to keys prefixed with "_" - e.g. "_id" is used for internal BibServer IDs. 331 | (BibServer also exposes records via the provided as well as the internal ID.)
332 |Another example
335 |
336 | {
337 | "type": "article",
338 | "title": "On a family of symmetric Bernoulli convolutions",
339 | "author": [
340 | {
341 | "name": "Erdös, Paul"
342 | }
343 | ],
344 | "journal": {
345 | "name": "American Journal of Mathematics"
346 | "identifier":[
347 | {
348 | "id": "0002-9327",
349 | "type": "issn"
350 | }
351 | ],
352 | "volume": "61",
353 | "pages": "974--976"
354 | },
355 | "year": "1939",
356 | "owner": "me",
357 | "id": "ID_1",
358 | "collection": "my_collection",
359 | "url": "http://example.com/me/my_collection/ID_1",
360 | "link":[
361 | {
362 | "url": "http://okfn.org",
363 | "anchor": "Open Knowledge Foundation"
364 | }
365 | ]
366 | }
367 |
368 | Linked data
376 |Rather than re-defining our own methods for representing linked data, 377 | we have adopted the JSON-LD linked data specification. This enables representation 378 | of your data in a BibJSON collection whilst also taking advantage of the power of 379 | linked data where necessary, without making the basics of BibJSON overly complex 380 | for those that do not require it. So in order to represent your data as linked data, 381 | just incorporate the JSON-LD linked data 382 | specifications when creating your BibJSON collection.
383 |JSON-LD example
386 |We would like to use real world examples as far as possible - do you require 387 | linked data functionality within BibJSON? If so, please 388 | contact us 389 | and we can work through a BibJSON / JSON-LD example with you.
390 |Parsing to BibJSON
398 |We have written parsers to BibJSON from a number of popular formats such as bibtex, 399 | CSV, RIS, MARC - and we have written BibServer to be easily extensible with additional 400 | parsers written in multiple programming languages. If we do not yet have the parser 401 | you require in our repo, get in touch and we will help you write one.
402 | 407 |The parse functionality can be run independently from the core of BibServer,so 408 | it is possible to create and expose your own parsers if you wish.
409 |Schema
412 |BibJSON is intended to be simple yet useful, and should be used 413 | as is most practical. There is no fixed schema as yet, but as JSON-LD is supported 414 | it is possible to reference any vocabulary via a namespace declaration and use it 415 | with your key/value pairs where necessary.
416 |Development is managed via our mailing list 417 | the Open biblio WG blog at http://openbiblio.net, 418 | and the wiki at http://wiki.okfn.org/Projects/openbibliography/bibjson.
419 |Why use / who uses BibJSON
425 | 431 |BibJSON data can be very easily displayed, searched, 432 | embedded, merged and shared on the internet via BibServer and similar tools. With that comes the ability to use 433 | your bibliographic metadata directly in online documents to manage, share and link your reference lists - not just 434 | maintaining your collection for use in static documents, but using your collections as part of the
435 |Let us know if you are using or considering using BibJSON for your own project. 436 | It becomes more useful as more people use it.
437 |Anything similar? (why not use them?)
440 |The concept of BibJSON is like that of GeoJSON.
441 |There are various other ways to represent your data and share it with other people. 442 | We have designed BibJSON around 443 | some key requirements - to be useful on the web, to remain simple, 444 | and to present consensus on usage.
445 |We think that the power of linked data is good where necessary, and we support that via 446 | our adoption of JSON-LD. We prefer it over others such as RDF/JSON as it enables us to 447 | maintain a simple key/value structure where appropriate.
448 |What do you think?
456 |We would like to know what you think about BibJSON. We would like to find out where it actually is useful for other people.
457 |The best place to get in touch is on our mailing list openbiblio-dev@lists.okfn.org.
458 |It would be great to hear back about any potential uses of BibJSON, or any interest in converting records or collections, or in writing parsers 459 | to do so. Also, any follow up comments about the conventions described here, or suggestions for additions / changes, should be presented 460 | to the mailing list for consideration.
461 |