#qbProject

qbProject is a set of scala libraries around JSON and API development using the Play Framework.

Developed by M Cube, EclipseSource and Contributors 2014. Licensed under Apache License 2.

###qbSchema The core component is qbSchema, a library allowing to declare JSON schemas which can be used for validation, transformation and meta description for your JSON entities. Especially the meta descriptions open ups some very useful usecases: It can be exported and consumed by UI generation libraries. It helps with data imports from different sources (e.g CSV) and it can be used to inject schemas/validation to your application at runtime.

Defining a schema is as simple as:

val todoSchema = qbClass(
  "title" -> qbString(maxLength(140)),
  "description" -> qbString,
  "dueDate" -> qbDateTime
)

Then it can be used for validation of JSON. It uses JsResult from Play for monadique results and proper error aggregation.

val input = Json.obj(
  "title" -> "Hello World",
  "description" -> "Say hello to all the peeps out there",
  "dueDate" -> new DateTime().toString()
)

// Validate JSON directly
val result: JsResult[JsObject] = QBValidator.validate(todoSchema)(input)

// Or use the Action provided by qbplay
def echoAction = ValidatingAction(todoSchema) { 
  request => Ok(request.validatedJson)
}

qbSchema offers a variety of schema manipulation operations, so-called SchemaOps. They allow to add and remove fields, merge schemas, make fields optional and so on.

// make the description field optional
val optionalDescriptionSchema = todoSchema ? "description"

// add an author to the todoSchema
val todoWithAuthor = todoSchema ++ qbClass( 
  "author" -> qbClass(
    "name" -> qbString,
    "email" -> qbEmail
  )
)

qbSchemas can be serailized to JSON schema, which can be used for JSON schema compliant clients such as form generators. qbSchema can also be generated by incoming JSON schema. This allows to inject new schemas into your system at runtime.

Json.prettyPrint(Json.toJson(todoSchema))

results in a JSON schema based representation:

{
  "type" : "object",
  "properties" : {
    "title" : {
      "type" : "string",
      "maxLength" : 140
    },
    "description" : {
      "type" : "string"
    },
    "dueDate" : {
      "type" : "string",
      "format" : "date-time"
    }
  },
  "additionalProperties" : false,
  "required" : [ "title", "description", "dueDate" ]
}

qbSchema was designed with extensibility in mind and as such allows introducing new types or annotating existing types with rules or additional meta data.

// Define your new QBType
class QBImage(rules: Set[ValidationRule[JsString]]) extends QBStringImpl(rules)
// Create a DSL helper
def image = new QBImage(Set.empty)

// Create a schema with your newly created type.
val schema = qbClass("img" -> image)
val instance = Json.obj("img" -> "otto.png")

val isQBImage = (qbType: QBType) => qbType.isInstanceOf[QBImage]

// Use the helpers provided by QB to transform your JSON. E.g. prepending an URL to every QBImage type.
schema.transform(instance)(
  isQBImage -> { case JsString(path) => JsString("public/images/" + path) }
)

###qbMongo // TODO: describe mongo integration

###qbPlay //TODO: describe

###qbCSV qbCSV is an adapter for qbSchema, it allows transforming CSV to JSON using the meta description of the schema.

//TODO: describe

Getting started

For a tutorial on how to get started please see the qb homepage.

// Add a resolver
"QB repository" at "http://dl.bintray.com/qbproject/maven"

// Add these dependencies
val qbSchema        = "org.qbproject"    %% "qbschema"    % "0.4.1.2"
val qbPlay          = "org.qbproject"    %% "qbplay"      % "0.4.1.2"
val qbCSV           = "org.qbproject"    %% "qbcsv"       % "0.4.1.2"

Contribute

QB is under constant developement and we appreciate any feedback, suggestions, feature requests, bug reports or contributions.

So please don't hesitate to open an issue on the bugtracker or drop us an email.

Build

We use Travis CI to build qb:

edgarmueller/qbproject

#qbProject

Getting started

Contribute

Build