granitic-yaml
Extension to Granitic to support YAML configuration and component definition files instead of JSON.
Pre-requisites
You must be using Granitic 1.3 or later
Instructions for use
Open a terminal and run
go get github.com/graniticio/granitic-yaml
Install YAML specific versions of Granitic tools
go install github.com/graniticio/granitic-yaml/cmd/grnc-yaml-bind
go install github.com/graniticio/granitic-yaml/cmd/grnc-yaml-project
If you will only be using YAML for your Granitic projects, you might want to remove the JSON versions of the tools to avoid confusion.
rm $GOPATH/bin/grnc-project
rm $GOPATH/bin/grnc-bind
Modifying your existing projects
Go files
Your existing JSON-based projects will have a main
file where Granitic is invoked (usually in the root of your project and called service.go
)
You will need to change the import in this file from:
import "github.com/graniticio/granitic"
to
import "github.com/graniticio/granitic_yaml"
and the line that invokes Granitic from
granitic.StartGranitic(bindings.Components())
to
granitic_yaml.StartGraniticWithYaml(bindings.Components())
JSON files
Your can use an online tool to convert your JSON files to YAML or re-create them by hand. They must be saved with
either a yml
or yaml
extension. If you are serving your configuration files with a web-server, the content type
should be set to one of:
text/x-yaml
application/yaml
text/yaml
application/x-yaml
If you are using an online tool you may find that string lists are converted to the verbose YAML syntax which may make Granitic validation rules unreadable. See the FAQ and examples section below for more examples.
FAQ
Why isn't this feature part of the Granitic core?
The Granitic core has a firm design principle of not requiring any downstream dependencies. As YAML support is not included in Go and requires a third-party library, YAML support is included as a separate package.
Can I include comments in component defintion and configuration files?
Yes
Can I mix and match YAML and JSON component definition files?
Not at this time.
Can I mix and match YAML and JSON configuration files?
Yes - because Granitic's internal facilities configuration is JSON based, this was a required feature.
What list syntax should I use?
YAML has two ways of representing lists:
MyList:
- Element1
- Element2
MyList: [Element1, Element2]
The first is generally considered more idiomatic, but the second can be more readable, especially for Granitic's validation rules. See the examples below.
Which YAML parser is being used?
https://github.com/go-yaml/yaml
Why don't empty projects created with grnc-yaml-project start?
The YAML parser removes empty structures, because the template YAML files created by the tool don't specify any components or packages, the sections are removed by the parser and Granitic won't start. As soon you add at least one package and component your project will start.
Examples
The following examples show YAML versions of the component definition files and configuration files from Granitic's Advanced validation tutorial
Component definition file
packages:
- github.com/graniticio/granitic/ws/handler
- granitic-tutorial/recordstore/endpoint
- github.com/graniticio/granitic/validate
- github.com/go-sql-driver/mysql
- granitic-tutorial/recordstore/db
components:
# GET Artist components
artistLogic:
type: endpoint.ArtistLogic
EnvLabel: conf:environment.label
artistHandler:
type: handler.WsHandler
HttpMethod: GET
Logic: ref:artistLogic
PathPattern: "^/artist/([\\d]+)[/]?$" #Complex strings with escapes should be quoted
BindPathParams:
- Id
FieldQueryParam:
NormaliseName: normalise
# POST Artist components
submitArtistLogic:
type: endpoint.SubmitArtistLogic
submitArtistHandler:
type: handler.WsHandler
HttpMethod: POST
Logic: ref:submitArtistLogic
PathPattern: "^/artist[/]?$"
AutoValidator: ref:submitArtistValidator
submitArtistValidator:
type: validate.RuleValidator
DefaultErrorCode: INVALID_ARTIST
Rules: conf:submitArtistRules
# Database access components
dbProvider:
type: db.MySqlProvider
Config: ref:dbConnection
dbConnection:
type: mysql.Config
User: grnc
Passwd: "OKnasd8!k"
Addr: localhost
DBName: recordstore
Configuration file
# Framework configuration
Facilities:
HttpServer: true
JsonWs: true
RuntimeCtl: true
ServiceErrorManager: true
QueryManager: true
RdbmsAccess: true
ApplicationLogger:
GlobalLogLevel: INFO
QueryManager:
ProcessorName: sql
# Application configuration
environment:
label: DEV
# Rules are more readable using the terse form of YAML lists - any YAML control characters (colons) need to be in quotes
submitArtistRules:
- [Name, STR, 'REQ:NAME_MISSING', TRIM, STOPALL, 'LEN:5-50:NAME_BAD_LENGTH', BREAK, 'REG:^[A-Z]| +$:NAME_BAD_CONTENT']
- [FirstYearActive, INT, 'RANGE:1700|2100:FIRST_ACTIVE_INVALID']
# As are service errors, but as messages are likely to contain commas, put them in quotes
serviceErrors:
- [C, INVALID_ARTIST, "Cannot create an artist with the information provided."]
- [C, NAME_MISSING, "You must supply the Name field on your submission."]
- [C, NAME_BAD_LENGTH, "Names must be 5-50 characters in length."]
- [C, NAME_BAD_CONTENT, "Names can only contain letters and spaces."]
- [C, FIRST_ACTIVE_INVALID, "FirstYearActive must be in the range 1700-2100"]