Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 115 lines (93 sloc) 4.882 kB
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
1 # MLJSON - A JSON Facade on top of MarkLogic
d17d16b @ryangrimm Updated.
authored
2
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
3 The MLJSON project is a set of libraries and REST endpoints to enable the MarkLogic Server to become an advanced JSON store.
d17d16b @ryangrimm Updated.
authored
4
86f6c76 @eedeebee
eedeebee authored
5 #### [MarkLogic Server]
239673c @eedeebee Edited README.markdown via GitHub
eedeebee authored
6 - High-performance, scalable database for unstructured information
7 - "NoSQL" datastore (no tables, rows, columns) - just documents and unique IDs (URIs).
8 - Uses XML datamodel for documents, query-able via XQuery, XSLT, XPath
86f6c76 @eedeebee
eedeebee authored
9 - Uses search-engine techniques to efficiently expose real-time fulltext search
239673c @eedeebee Edited README.markdown via GitHub
eedeebee authored
10 - ACID-compliant CRUD (Create, Read, Update, Delete)
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
11
86f6c76 @eedeebee
eedeebee authored
12 #### [JSON]
8971d98 @eedeebee Edited README.markdown via GitHub
eedeebee authored
13 - JavaScript Object Notation
14 - A lightweight data-encoding and interchange format
15 - Native to JavaScript, now widely utilized across languages
16 - Commonly used for passing data to web browsers
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
17
18 ## Design goal
86f6c76 @eedeebee
eedeebee authored
19 Enable developers to store and search/query JSON inside MarkLogic (without knowledge of XQuery, XSLT, or XPath)
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
20
86f6c76 @eedeebee
eedeebee authored
21 #### Design considerations:
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
22 1. Approach things from a JSON angle
23 - Create the XML to match the JSON, not vice-versa
24 2. Make good use of MarkLogic indexes
25 - Craft the XML so it's fast to query
26 3. XML representation of JSON is an implementation detail - users only need think in terms of JSON
27
86f6c76 @eedeebee
eedeebee authored
28 #### Overview
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
29 MLJSON exposes REST endpoints that allow a developer to
d17d16b @ryangrimm Updated.
authored
30 easily store and retrieve JSON documents from the database ([CRUD]). It also
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
31 exposes a very powerful query interface that uses a native JSON syntax:
d17d16b @ryangrimm Updated.
authored
32
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
33 Query Using native JSON syntax
34 - Don't expose the XML internals to users
35 - Support full range of MarkLogic indexes
d17d16b @ryangrimm Updated.
authored
36
b07c782 @eedeebee Edited README.markdown via GitHub
eedeebee authored
37 This query interface allows the user to find documents via "path" expressions as
38 well as full text search expressions. For those familiar with MarkLogic, it
39 exposes all of the functionality found in the [CTS search functions].
86f6c76 @eedeebee
eedeebee authored
40
41 #### Presentation
42 Here are some [slides] from a presentation on MLJSON given at XML Prague 2011.
43
e8209f7 @ryangrimm Some documentation.
authored
44 ___
45
46 ## Files
47 - lib/json.xqy - Has two public functions:
48 - jsonToXML - parses a JSON string into XML that can be stored in MarkLogic
f94b435 @ryangrimm Warning: Method signatures and functionality has changed!
authored
49 - xmlToJSON - parses the generated XML into a JSON string
e8209f7 @ryangrimm Some documentation.
authored
50 - lib/json-path.xqy - Tinkering with ways to query the stored JSON
8fc9270 @ryangrimm No longer need the query parsing library.
authored
51 - jsonquery.xqy - A REST endpoint for querying JSON documents
e8209f7 @ryangrimm Some documentation.
authored
52 - jsonstore.xqy - A REST endpoint for storing, managing and retrieving JSON documents
53
54 ## Capabilities of jsonstore.xqy
55 #### Insert a JSON document
56 - Request type: PUT
57 - Request body should be the JSON document
58 - Example: jsonstore.xqy?uri=/foo/bar.json
59 - Optional: When inserting a document you can set permissions, collections and a document quality.
60 - jsonstore.xqy?uri=/foo/bar.json&permission=public:read&permission=admin:write
61 - jsonstore.xqy?uri=/foo/bar.json&collection=public&collection=published
62 - jsonstore.xqy?uri=/foo/bar.json&quality=10
63 - jsonstore.xqy?uri=/foo/bar.json&permission=public:read&collection=public&quality=10
f1c8dc3 @ryangrimm Better markdown.
authored
64
e8209f7 @ryangrimm Some documentation.
authored
65 #### Get a JSON document
66 - Request type: GET
67 - Example: jsonstore.xqy?uri=/foo/bar.json
f1c8dc3 @ryangrimm Better markdown.
authored
68
e8209f7 @ryangrimm Some documentation.
authored
69 #### Delete a JSON document
70 - Request type: DELETE
71 - Example: jsonstore.xqy?uri=/foo/bar.json
f1c8dc3 @ryangrimm Better markdown.
authored
72
e8209f7 @ryangrimm Some documentation.
authored
73 #### Set a property on a document
74 - Request type: POST
75 - Properties are **not** held inside the JSON document, properties are stored outside of the document and don't effect the stored document at all. They are best thought of as metadata about the document but should be avoided if possible due to storage overhead.
76 - Example: jsonstore.xqy?uri=/foo/bar.json&property=publishState:final&property=needsEditorial:false
f1c8dc3 @ryangrimm Better markdown.
authored
77
e8209f7 @ryangrimm Some documentation.
authored
78 #### Get a property of a document
79 - Request type: GET
80 - Returns the value of a property that has been set on a document.
81 - Example: jsonstore.xqy?uri=/foo/bar.json&property=publishState
f1c8dc3 @ryangrimm Better markdown.
authored
82
e8209f7 @ryangrimm Some documentation.
authored
83 #### Set permissions on a document
84 - Request type: POST
85 - When setting permissions on a document, all of the existing permissions are overwritten.
86 - Example: jsonstore.xqy?uri=/foo/bar.json&permission=public:read&permission=admin:write
f1c8dc3 @ryangrimm Better markdown.
authored
87
e8209f7 @ryangrimm Some documentation.
authored
88 #### Set collections on a document
89 - Request type: POST
90 - When setting collections on a document, all of the existing collections are overwritten.
91 - Example: jsonstore.xqy?uri=/foo/bar.json&collection=public&collection=published
f1c8dc3 @ryangrimm Better markdown.
authored
92
e8209f7 @ryangrimm Some documentation.
authored
93 #### Set the quality of a document
94 - Request type: POST
95 - Example: jsonstore.xqy?uri=/foo/bar.json&quality=10
96
97 ## TODO
98 - lib/json.xqy:
99 - Convert wide encoded unicode chars: \uFFFF\uFFFF
100 - Sanitize element names
101 - jsonstore.xqy:
102 - Move a document
103 - Copy a document
104 - Get the document permissions
105 - Get the document collections
106 - Get the document quality
107 - Some real tests
108
86f6c76 @eedeebee
eedeebee authored
109 [MarkLogic]: http://developer.marklogic.com
110 [MarkLogic Server]: http://developer.marklogic.com
d17d16b @ryangrimm Updated.
authored
111 [CRUD]: http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
112 [CTS search functions]: http://developer.marklogic.com/pubs/4.2/apidocs/cts-query.html
86f6c76 @eedeebee
eedeebee authored
113 [JSON]: http://json.org
114 [slides]: http://www.xmlprague.cz/2011/presentations/jason-hunter-mljson.pdf
Something went wrong with that request. Please try again.