add schema for meta-data JSONs

:Release Notes: Introduced service meta-data description json schema. :Detailed Notes: schemas for: - category - map of category name to category format - generic reply (to be referenced by library clients) :Testing Performed: jsonlint :QA Notes: :Issues Addressed: [BHV-1587] Design category description format [BHV-1588] Create JSON schema for category description Open-webOS-DCO-1.0-Signed-off-by: Nikolay Orliuk <nikolay.orliuk@lge.com> Change-Id: I4f2dfbd7428315dd035d26eadbefa6dcc89a6b6a Reviewed-on: https://g2g.palm.com/5003 Reviewed-by: DCO Verification Reviewed-by: Nikolay Orliuk <nikolay.orliuk@lge.com> Tested-by: Nikolay Orliuk <nikolay.orliuk@lge.com> Reviewed-by: Anatolii Sakhnik <anatolii.sakhnik@lge.com>
openwebos · Mar 26, 2014 · ed3787e · ed3787e
1 parent 3b17fcc
commit ed3787e
Show file tree

Hide file tree

Showing 7 changed files with 266 additions and 1 deletion.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -126,6 +126,11 @@ webos_build_pkgconfig()
 webos_config_build_doxygen(doc Doxyfile)
 webos_build_system_bus_files()
 
+install(DIRECTORY files/schema/
+	DESTINATION ${WEBOS_INSTALL_WEBOS_SYSCONFDIR}/schemas/luna-service2
+	PATTERN "*.schema"
+	)
+
 # install the script file
 webos_configure_source_files(LS-CONTROL files/scripts/public/ls-control)
 install(PROGRAMS ${LS-CONTROL} DESTINATION ${WEBOS_INSTALL_SBINDIR} ${LS2_PERMS})

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -82,7 +82,7 @@ EXCLUDE_PATTERNS       =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = @PROJECT_SOURCE_DIR@/doc/examples
 EXAMPLE_PATTERNS       = 
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             = 

diff --git a/doc/examples/simpleBiffService.schema b/doc/examples/simpleBiffService.schema
@@ -0,0 +1,70 @@
+{
+    // probably the easiest way is to load whole json and use specific parts
+    // for specific categories
+    "/" : {
+        "definitions": {
+            "sender": {
+                "type": "object",
+                "properties": {
+                    "id": { "type": "string" },
+                    "name": { "type": "string" },
+                    "organization": { "type": "string" }
+                },
+                "required": ["id"],
+                "additionalProperties": false
+            },
+            "messageInfo": {
+                "type": "object",
+                "properties": {
+                    "id": "integer",
+                    "sender": { "$ref": "#/definitions/sender" },
+                    "subject": { "type": "string" }
+                },
+                "required": ["id"],
+                "additionalProperties": false
+            }
+        },
+        "methods": {
+            "leaveMessage" : {
+                "call" : {
+                    "type": "object",
+                    "properties": {
+                        "sender": { "$ref": "#/definitions/sender" },
+                        "subject": { "type": "string" },
+                        "body": { "type": "string" }
+                    },
+                    "additionalProperties": false
+                },
+                "reply": { // since "firstReply" ommited "reply" used for all answers
+                    "type": "integer",
+                    "description": "message id"
+                }
+            },
+            "unreadMessages" : {
+                "call": {
+                    "type": "object",
+                    "properties": {
+                        "lastId": {
+                            "type": "integer",
+                            "description": "last read message id (0 if none)",
+                            "default": 0
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                "firstReply": { // first reply consist of bunch of messages since last request
+                    "type": "object",
+                    "properties": {
+                        "unread": {
+                            "type": "array",
+                            "items": { "$ref": "#/definitions/messageInfo" }
+                        },
+                        "lastId": { "type": "integer" }
+                    }
+                },
+                // further subscription replies are simply messageInfo's
+                "reply": { "$ref": "#/definitions/messageInfo" },
+            }
+        }
+    }
+}
diff --git a/files/schema/category.schema b/files/schema/category.schema
@@ -0,0 +1,73 @@
+{
+    "id": "resources://luna-sevice2/category",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "description": "luna-service2 category description schema",
+    "properties": {
+        "definitions": {
+            "description": "schemas for local referencing",
+            "additionalProperties": { "$ref": "http://json-schema.org/draft-04/schema#" },
+            "default": {}
+        },
+        "methods": {
+            "type": "object",
+            "description": "dictionary of category methods",
+            "additionalProperties": {
+                "type": "object",
+                "description": "method meta-information",
+                "properties": {
+                    "call": {
+                        "description": "schema for params passed to service call",
+                        "allOf": [{ "$ref": "http://json-schema.org/draft-04/schema#" }],
+                        "default": {}
+                    },
+                    "firstReply": {
+                        "description": "schema for content of first service reply on call (omitted means all responses are the same)",
+                        "allOf": [{ "$ref": "http://json-schema.org/draft-04/schema#" }]
+                    },
+                    "reply": {
+                        "type": "object",
+                        "description": "schema for content of service replies on call (subsequent only if firstReply present)",
+                        "allOf": [{ "$ref": "http://json-schema.org/draft-04/schema#" }],
+                        "default": {
+                            "description": "general response schema",
+                            "oneOf": [
+                                {
+                                    "type": "object",
+                                    "description": "general successful response schema",
+                                    "properties": {
+                                        "returnValue": {
+                                            "description": "call successful result indicator",
+                                            "enum": [true]
+                                        }
+                                    },
+                                    "required": ["returnValue"]
+                                },
+                                {
+                                    "type": "object",
+                                    "description": "general error response schema",
+                                    "properties": {
+                                        "returnValue": {
+                                            "description": "call unsuccessful result indicator",
+                                            "enum": [false]
+                                        },
+                                        "errorCode": {
+                                            "type": "integer",
+                                            "description": "type of error indicator for client service"
+                                        },
+                                        "errorText": {
+                                            "type": "string",
+                                            "description": "human-readable error description"
+                                        }
+                                    },
+                                    "required": ["returnValue"]
+                                }
+                            ]
+                        }
+                    }
+                },
+                "additionalProperties": false
+            }
+        }
+    }
+}
diff --git a/files/schema/generalResponse.schema b/files/schema/generalResponse.schema
@@ -0,0 +1,39 @@
+{
+    "id": "resources://luna-service2/generalResponse",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "description": "general response schema",
+    "oneOf": [
+        {
+            "type": "object",
+            "description": "general successful response schema",
+            "properties": {
+                "returnValue": {
+                    "type": "boolean",
+                    "description": "call successful result indicator",
+                    "enum": [true]
+                }
+            },
+            "required": ["returnValue"]
+        },
+        {
+            "type": "object",
+            "description": "general error response schema",
+            "properties": {
+                "returnValue": {
+                    "type": "boolean",
+                    "description": "call unsuccessful result indicator",
+                    "enum": [false]
+                },
+                "errorCode": {
+                    "type": "integer",
+                    "description": "type of error indicator for client service"
+                },
+                "errorText": {
+                    "type": "string",
+                    "description": "human-readable error description"
+                }
+            },
+            "required": ["returnValue"]
+        }
+    ]
+}
diff --git a/files/schema/service.schema b/files/schema/service.schema
@@ -0,0 +1,9 @@
+{
+    "id": "resources://luna-service2/service",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "description": "schema for consolidated view of all categories exposed by service",
+    "additionalProperties": {
+        "$ref": "category"
+    }
+}
diff --git a/include/public/luna-service2/lunaservice-meta.h b/include/public/luna-service2/lunaservice-meta.h
@@ -0,0 +1,69 @@
+/****************************************************************
+ * @@@LICENSE
+ *
+ * Copyright (c) 2014 LG Electronics, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * LICENSE@@@
+ ****************************************************************/
+
+/**
+ *  @file lunaservice-meta.h
+ */
+
+#ifndef __LUNASERVICE_META_H
+#define __LUNASERVICE_META_H
+
+#include <pbnjson.h>
+
+/**
+ * @defgroup LunaServiceMeta
+ * @ingroup LunaService
+ * @brief Luna Service meta-information manipulation
+ */
+
+/**
+ * @addtogroup LunaServiceMeta
+ * @{
+ */
+
+/**
+ * Specify meta information about category
+ *
+ * Set JSON value that describes specified category. Provides validation schema
+ * for input params and replies. Gives some description for calls etc.
+ *
+ * @param sh  handle that identifies registered service on bus
+ * @param category  identifier of category this information provided for
+ * @param description  information itself (no ownership transfer)
+ *                     @ref simpleBiffService.schema "see / category in example"
+ * @param error  ouptut buffer for error description if applicable
+ * @return  false in case of error
+ */
+bool LSCategorySetDescription(
+	LSHandle *sh, const char *category,
+	jvalue_ref description,
+	LSError *error
+);
+
+/**
+ * @example simpleBiffService.schema
+ * Service description example
+ */
+
+/* TODO */
+
+/* @} END OF LunaServiceMeta */
+
+#endif